Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 003 / wampum32.arc / WAMPUM32.EXE / WAMPUM.DOC < prev next >

Wrap

Text File | 1988-02-14 | 265.9 KB | 5,483 lines

WAMPUM User's Guide Copyright (c) Ward Mundy, 1986, 1987. All Rights Reserved. 1 Overview . . . . . . . . . . . . . . . . . . . . . . . . 1 1.1 What is WAMPUM Anyway? . . . . . . . . . . . . . . . 1 1.2 Summary of Features . . . . . . . . . . . . . . . . 1 1.3 New Features in Version 3.1 . . . . . . . . . . . . 2 1.4 System Requirements . . . . . . . . . . . . . . . . 2 1.5 Getting Started . . . . . . . . . . . . . . . . . . 3 1.5.1 Loading the Program . . . . . . . . . . . . . . 3 1.5.1.1 Where to Put It . . . . . . . . . . . . . 3 1.5.1.2 How to Run It . . . . . . . . . . . . . . 3 1.5.2 Maneuvering on the Main Menu . . . . . . . . . 4 1.6 Quitting WAMPUM . . . . . . . . . . . . . . . . . . 4 1.7 Using the Cursor & Function Keys . . . . . . . . . . 5 2 End-User Functions . . . . . . . . . . . . . . . . . . . 6 2.1 Overview . . . . . . . . . . . . . . . . . . . . . 6 2.2 A - ADDing New Records . . . . . . . . . . . . . . 7 2.3 E - EDITing Records . . . . . . . . . . . . . . . . 8 2.4 D - DISPLAYing Records . . . . . . . . . . . . . . 10 2.5 M - MARKing a Record for Deletion . . . . . . . . . 11 2.6 U - UNDELETing a Record . . . . . . . . . . . . . . 13 2.7 P - PRINTing Records . . . . . . . . . . . . . . . 15 2.8 X - REBUILD/FileFix . . . . . . . . . . . . . . . . 16 2.9 S - SELECT Utilities . . . . . . . . . . . . . . . 17 2.9.1 Overview . . . . . . . . . . . . . . . . . . . 17 2.9.2 Record Selection Criteria . . . . . . . . . . . 18 2.9.3 Listing File Contents . . . . . . . . . . . . . 23 2.9.4 Changing Current Data Entry Menu . . . . . . . 23 2.9.5 Picking the Lead Index . . . . . . . . . . . . 24 2.9.6 Setting Browse Mode ON . . . . . . . . . . . . 24 2.9.7 Listing the File Structure . . . . . . . . . . 25 2.10 R - REPORTS Generation . . . . . . . . . . . . . . 25 2.11 L - LABELS Production . . . . . . . . . . . . . . . 26 2.12 T - FORM LETTER Generation . . . . . . . . . . . . 27 2.13 W - WAMPUM Preformatted Output . . . . . . . . . . 28 2.14 Printer Selection Screen . . . . . . . . . . . . . 29 2.14.1 Printed Output . . . . . . . . . . . . . . . . 29 2.14.2 Output All Records . . . . . . . . . . . . . . 29 2.14.3 Output Records Marked for Deletion . . . . . . 29 2.15 On-Line HELP . . . . . . . . . . . . . . . . . . . 29 3 Developer Functions . . . . . . . . . . . . . . . . . . . 31 3.1 Creating A New Application . . . . . . . . . . . . 31 3.1.1 Overview of Application Development Strategy . 31 3.1.2 Create A New SubDirectory . . . . . . . . . . 32 3.1.3 Building a New File . . . . . . . . . . . . . 33 3.1.4 Selecting the New File . . . . . . . . . . . . 34 3.1.5 Revising the Existing File Structure . . . . . 34 3.1.6 Indexing the New File . . . . . . . . . . . . 35 3.1.6.1 Overview . . . . . . . . . . . . . . . . . 35 3.1.6.2 Creating New Indexes . . . . . . . . . . . 36 3.1.6.3 Selecting Indexes . . . . . . . . . . . . 37 3.1.7 Printer Configuration (.MEM file) . . . . . . 37 3.1.7.1 Overview . . . . . . . . . . . . . . . . . 37 3.1.7.2 Selecting an Existing Printer Table . . . 38 3.1.7.3 Creating a New Printer Table . . . . . . . 39 3.1.8 Relating a Secondary File . . . . . . . . . . 40 3.1.9 Storing the New Configuration (WAMPUM.MEM) . . 41 3.1.10 Building Reports, Labels, and Form Letters . . 41 3.1.10.1 REPORTS . . . . . . . . . . . . . . . . . 41 3.1.10.1.1 Overview . . . . . . . . . . . . . . 41 3.1.10.1.2 Creating A New Report Format . . . . 42 3.1.10.1.3 Modifying Existing Report Formats . 48 3.1.10.1.4 Outputting MEMO fields in Reports . 48 3.1.10.2 LABELS . . . . . . . . . . . . . . . . . 49 3.1.10.2.1 Overview . . . . . . . . . . . . . . 49 3.1.10.2.2 Creating A New Label Format . . . . 50 3.1.10.2.3 Modifying An Existing Label Format . 51 3.1.10.3 FORM LETTERS . . . . . . . . . . . . . . 52 3.1.10.3.1 Overview . . . . . . . . . . . . . . 52 3.1.10.3.2 Creating a New Form Letter File . . 52 3.1.10.3.3 Building Data in Form Letter File . 52 3.1.10.3.4 WAMPUM Field Data Expressions . . . 54 3.1.11 Building Function Key Macros (KEYS.DBF) . . . 56 3.1.12 Building Edit Checks (EDIT.DBF) . . . . . . . 58 3.1.13 Building Data Entry Menus (MENUS.DBF) . . . . 64 3.1.14 Building an Audit Trail File (AUDIT.DBF) . . . 66 3.1.15 Preformatted Output (WAMPUM.DBF) . . . . . . . 66 3.1.15.1 Overview . . . . . . . . . . . . . . . . 66 3.1.15.2 Building the WAMPUM File . . . . . . . . 67 3.1.15.3 Adding/Editing the WAMPUM File . . . . . 67 3.1.16 Resetting the Developer Password . . . . . . . 68 3.1.17 Network Considerations . . . . . . . . . . . . 69 3.1.18 Making a Backup of the User Application . . . 70 3.1.19 Writing the Documentation . . . . . . . . . . 70 3.2 ! - RUNning an External Program . . . . . . . . . . 70 3.3 Z - ZOOMing or RELATing a Supplemental File . . . . 71 3.4 G - Global Replacement of Data . . . . . . . . . . 72 3.5 C - Copy Utilities for Importing & Exporting Data . 73 3.6 Deleting & Undeleting Groups of Records . . . . . . 75 3.7 Reserved Variables, dBASE & Clipper Functions . . . 76 3.7.1 Overview . . . . . . . . . . . . . . . . . . . 76 3.7.2 CHARACTER/STRING functions . . . . . . . . . . 76 3.7.3 DATE functions . . . . . . . . . . . . . . . . 77 3.7.4 DUPKEY("FIELDNAME") prevents duplicate keys . . 78 3.7.5 EMPTY(fieldname) tests for empty fields . . . . 78 3.7.6 LASTTIME field in data bases . . . . . . . . . 79 3.7.7 LASTUPDT field in data bases . . . . . . . . . 79 3.7.8 LASTUSER field in data bases . . . . . . . . . 79 3.7.9 MEMOTRAN(fieldname) outputs MEMO fields . . . . 79 3.8 PATH considerations . . . . . . . . . . . . . . . 79 3.9 Enabling USERID's and Passwords . . . . . . . . . . 80 3.10 WAMPUM & DOS System Errors . . . . . . . . . . . . 81 3.11 Credits . . . . . . . . . . . . . . . . . . . . . . 81 1 Overview 1.1 What is WAMPUM Anyway? Ward's Automated Menu Package Using Microcomputers (WAMPUM) is a full-featured, menu-driven implementation of the dBASE III programming language. Version 3.1 adds network support while remaining both an application development tool and an end-user data base management system. WAMPUM is a copyrighted work owned by Ward Mundy. The software is licensed for use under certain terms and conditions which are displayed when you run or terminate the running of the program. A copy of the license agreement accompanies this documentation. Read the terms of the license carefully before using or copying the software! If you do not agree with the license terms, you may discontinue use of the software at any time. Special thanks to Nantucket, Inc., the developer of Clipper, the premier dBASE III compiler. Without Clipper, there would be no WAMPUM. Clipper's flexibility and many enhancements over Ashton-Tate's dBASE interpreters made development of WAMPUM a true labor of love. We also express our sincere appreciation to Nantucket for authorizing the distribution of their REPORT.EXE and LABEL.EXE programs to end-users without additional charge. These two programs simulate the dBASE III commands of CREATE REPORT and CREATE LABEL and make WAMPUM a complete stand-alone application development system without reliance upon any dBASE interpreter. 1.2 Summary of Features As noted, WAMPUM provides much of the functionality of dBASE III through its simple menu interface. Some of the features included in WAMPUM are outlined below. For a more detailed look at individual features, consult that section of the User's Guide. Key features include: * Creation and use of dBASE III-compatible data bases * Complete multi-user network support using any dBASE file * Field types include: Char, Numeric, Date, Logical, Memo * Creation and use of up to 7 B-Tree Indexes per .DBF file * Add, Edit, Delete, & Undelete Records in any .DBF file * Display, List and Print Records from any .DBF file * 10 Data Entry Screen Formats tailored to any application * Creation and use of dBASE III-compatible reports & labels * Creation and use of WAMPUM "mail merge" form letter files * Relation of second data base by key for any output format * Full-featured copy utilities to import & export any data * Creation of printer templates to support up to 10 fonts * Library of preformatted output forms with sort & select * Library of edit-checks tailored to any .DBF file system * Library of macros tailored to any WAMPUM application * Calculated fields using standard dBASE expressions * File and index packing to restore damaged data bases - 1 - * Automated Selection Assist for complex Boolean searches * Boolean searches of dBASE III-compatible MEMO fields * Audit Trail / Transaction Logging for multi-user tasks * NetBIOS-compatible record & file locking network support * Global search & replace of any data elements in one pass 1.3 New Features in Version 3.1 WAMPUM 3.1 provides many new features as well as a number of refinements suggested by existing users. If you already are using version 3.0, you may wish to scan the new features summary below rather than re-reading the entire User's Guide. For ease of reference, new features are summarized here as well as in the appropriate section of this User's Guide. Key new features of version 3.1 include: * Complete multi-user network support using any dBASE file * NetBIOS-compatible record & file locking network support * Creation and use of up to 7 B-Tree Indexes per .DBF file * Global search & replace of 10 data elements in one pass * Manipulation of any 5 related data bases in form letters * Index key retrieval for production of single form letters * Automatic posting of LASTUSER information in data base * PASSWORD protection system for network environments * Customized USER configurations for network environments * Specification of particular fields for use in BROWSE mode * Simplified file structure modification like dBASE III's * Multi-drive support for storage of data bases & indexes * Forced field confirmation with <ENTER>, if desired * Enhanced documentation outlining many dBASE functions 1.4 System Requirements WAMPUM 3.1 may be used on any IBM PC-compatible computer running DOS 2.0 or higher with a hard disk. For multi-user network applications, DOS 3.1 or higher is required on every computer as well as an IBM NetBIOS-compatible network. For performance reasons, an 80286 or 80386 processor is desirable. Minimum memory requirement is 320K above and beyond the memory requirements of DOS and any memory-resident programs in use. Minimum memory is 420K (with DOS 3.1) to link to REPORT and LABEL programs from within WAMPUM. Without much in the way of memory-resident software, WAMPUM typically needs 512K to operate satisfactorily after loading DOS. WAMPUM will run on either a monochrome or color display. In the case of certain compatibles such as Compaq, WAMPUM should be run in forced monochrome mode by issuing the command WAMPUM MONO. Because WAMPUM creates a number of work files from time to time, and because WAMPUM typically works with numerous files open at the same time, you will need to make sure that when your - 2 - computer is started, a file named CONFIG.SYS exists in the root directory of the boot disk. This file must contain the following entries with the minimum values shown: FILES=20 BUFFERS=24 Failure to include the above commands will result in very unpredictable behavior of WAMPUM which could destroy data bases and indexes in use at the time of a very likely system crash! 1.5 Getting Started 1.5.1 Loading the Program 1.5.1.1 Where to Put It WAMPUM is an executable program with the name WAMPUM.EXE. It typically is distributed with several other programs including REPORT.EXE, LABEL.EXE, and several printer configuration files with a .MEM file extension. All of these should be copied into a directory on your hard disk which is included in the PATH command whenever you start up your system. This will assure that WAMPUM can be run from any subdirectory on your hard disk. If you are not familiar with the path command, consult your DOS manual for more details. Simply stated, the PATH command tells DOS which directories (other than the current one) should be searched whenever you ask the computer to run a program. In building systems, typically we set aside a directory called \UTIL to store applications software. This directory is included in the path command when the computer is started. If you have such a directory and it is in your PATH, then copy WAMPUM into this directory. 1.5.1.2 How to Run It WAMPUM is designed to support two, very different audiences. The first group is end-users, and the second is application developers. This design is implemented by providing two different menus for the two groups. The end-user menu is designed to let a user do the normal things that are done with a database: adding, editing, and deleting records; running reports and labels; selecting the primary index for input and output of data; and entering record selection criteria to narrow down which records are produced in listings and reports. Provision is also made to allow the end-user to rebuild a damaged data base or index typically occasioned by a power failure. The end-user mode is initiated by typing WAMPUM and pressing the <ENTER> key at the DOS prompt. WAMPUM's developer mode contains all of the options outlined above plus a number of additional options designed to allow a person to develop a data base application for others to use. You do NOT have to be a programmer to become a good WAMPUM developer! - 3 - The developer's mode allows the creation of new data files and indexes as well as reports, labels, and printer formats. It also provides access to the data files used to develop edit checks, data entry menus, macros, preformatted output, and form letters. Finally it allows for customization of applications through the storing of a configuration identifying the files, indexes, printer, and name of each application. The developer mode is initiated by typing WAMPUM VOODOO and pressing the <ENTER> key at the DOS prompt. As previously noted, if you are using WAMPUM on a compatible such as the COMPAQ which makes DOS think it has a color card even when using a monochrome display, then you may want to force WAMPUM into monochrome mode by starting it with WAMPUM MONO or WAMPUM VOODOO MONO. WAMPUM also uses both a Report Writer (REPORT.EXE) and a Label Generator (LABEL.EXE) to create report and label templates. Depending upon the amount of memory in your machine, these programs may or may not be able to run from within the WAMPUM program itself. This User's Guide explains the procedure for running REPORT and LABEL from within WAMPUM. If you lack the necessary memory to do this, you may run the report writer from the DOS prompt by typing REPORT filename where filename is the name of the report template you wish to create or edit. You may run the label generator from the DOS prompt by typing LABEL filename where filename is the name of the label template you wish to create or edit. 1.5.2 Maneuvering on the Main Menu Once you have started WAMPUM by executing one of the commands outlined above, you will see the WAMPUM logo and then the Main System Menu. Note that just below the menu is a one- line sentence of HELP regarding the highlighted option. You move between the options with the UP and DOWN cursor keys. The HOME key will take you to the first option on the menu, and the END key will move you to the last option. Execute a choice on the Main System Menu by pressing the <ENTER> key when the choice desired is highlighted or by typing the LETTER corresponding to the choice you wish to run. Using the first letter method, you do not have to press <ENTER>. Exit from WAMPUM to DOS and end the program by pressing the <ESC>ape key while the Main System Menu is displayed. Context-sensitive HELP on WAMPUM features is available by pressing the F1 function key on any screen. 1.6 Quitting WAMPUM As indicated, the <ESC> key is pressed to exit from WAMPUM to DOS from the Main System Menu. - 4 - 1.7 Using the Cursor & Function Keys A number of keys have special functions within the WAMPUM System. Oftentimes, these keys are not the same as what you may have used in previous dBASE III applications. Please scan through the summaries below before you attempt to either use or build a WAMPUM application. Throughout this manual, you will see references to multiple key combinations such as CTRL-W or ALT-F10. Whenever you see a hyphenated key combination such as these, it means hold down the first key, then tap the second key, then release both keys. For example, CTRL-W means hold down the CTRL key, then tap the W key (case does not matter), then release both keys. ALT-F10 means hold down the ALT key, then tap the F10 function key, then release both keys. We use the word "TAP" advisedly. Most PC's have a "keyboard buffer" which remembers keystrokes which may not yet have been displayed. Every key on the PC acts like a repeating key on a selectric typewriter. Thus, TAP means touch and release promptly! <ESC> is the all-purpose key which is used to get you out of trouble. From ANY screen, you can always press the ESCape key to exit without preserving what you already were doing. From the Main Menu, pressing ESC will terminate WAMPUM and return you to the computer's operating system level. Ctrl-W is WAMPUM's SAVE key. Pressing CTRL-W typically tells the computer to SAVE what is displayed on the screen and move on to the next step. If you are a previous dBASE III user, then CTRL-W is equivalent to dBASE III's CTRL-End key. Ctrl-Home moves the user to the first field on a data entry screen. Ctrl-End moves the user to the last field on a data entry screen. <Enter> or <Down> Cursor completes an entry in a field and moves the user to the next field, if any, on the screen. <Up> Cursor moves the user to the previous field, if any, on the screen. <PgDn> signifies that data entry for this screen of data has been completed and that the user wishes to SAVE the data and continue. <PgUp> signifies that data entry for this screen of data has been completed and that the user wishes to SAVE the data and continue backwards through the data base (except when ADDing new records to the data base). Ctrl-<Left> Cursor moves the cursor to the beginning of the current data entry field. Ctrl-<Right> Cursor moves the cursor to the end of the current data entry field. - 5 - Ctrl-Y deletes the contents of the current field from the cursor position to the end of the field. <Ins> toggles the computer between insert mode and strike-over mode. The word <INSERT> appears at the top of the screen when INSERT mode is active. <Del> deletes the character currently under the cursor. F1 function key is the all-purpose HELP key. It retrieves a screenload of helpful hints which are keyed to your position in the WAMPUM system. F2-F10 function keys are macros tailorable by the developer to hold any character string desired. The same is true for the SHIFT, ALT, and CONTROL key combinations with the ten function keys. In short, 39 keyboard macros can be designed for each WAMPUM application. 2 End-User Functions 2.1 Overview If you are just beginning to use WAMPUM, then skip to the next section on Developer Functions after reading this overview. The developer's section will explain the step-by-step process for building a new application. This section is designed to acquaint the end-user with information necessary to build and maintain an existing data base as well as how to extract information from an existing data base. End-users typically want to do two things with a data base. They want to add or change information in an existing file (INPUT functions), and they want to extract information from an existing file (OUTPUT functions). In WAMPUM, INPUT consists of ADDing new records, EDITing existing records, and DELETing or UNDELETing existing records. For network applications, only one person can edit any individual record at any given time. Multiple people may be adding new records at the same time. And multiple people may be editing different existing records at the same time. In WAMPUM, OUTPUT means you just want to look at or print something which already exists in the file. For network users, multiple people can be outputting information from the same file simultaneously. ALL output falls into one of two categories: single record output or multiple record output. Single record OUTPUT is quick because it typically involves retrieval of a single record by an indexed key. This output may consist of either DISPLAYing an individual record or PRINTing an individual record. In either case the end-user is prompted for - 6 - the key of the record to find, and WAMPUM will find it in less than a second even with extremely large data bases. The record is displayed or printed in its entirety just as the information is stored in the data base. Multiple record OUTPUT tends to be slower but more useful. It is slower because WAMPUM must make a full pass through the data base to find the records desired for output. It tends to be more useful because the output typically is formatted in such a way that the extracted data is more meaningful. Multiple record output ALWAYS involves three steps: (1) picking the lead index to specify the order in which the records will appear in the output, e.g. alphabetically, by date, or by part number; (2) selecting (i.e. narrowing down) the group of records which should be output using Boolean logic, e.g. find all the new accounts for January or just the new accounts with sales over $1,000,000; and (3) choosing the type of output desired: a list, report, mailing labels, or a form letter. A billing statement, an overdue notice, and monthly summary of accounts all are examples of multiple record output which can easily be produced using WAMPUM. You simply must master the above concepts before use of any data base management system can be of much value. If you don't understand the relationship between input and output and the various types of output, put this User's Guide aside and try reading this section again tomorrow. 2.2 A - ADDing New Records To add new records to any data base, that file must first be selected. Look at the bottom of the WAMPUM Main Menu to make sure that the file you want to use is already selected. If not, it can be selected using the F - File Select option in developer mode only. If the file you wish to work with is selected, then you should also consider whether there are indexes which you want automatically updated as you ADD new records to the file. If so, then these, too, must be selected before you ADD new records. You can determine which indexes are in use by looking at the bottom of the Main System Menu screen. New indexes can be created and/or opened using the I - Index Sel/Create option in developer mode only. Once you are working with the correct file and indexes, then ADDing records is as simple as highlighting the A - Add a New Record option and pressing <ENTER>. Or you may simply type an A while the Main System Menu is displayed. The screen will clear and WAMPUM will display a data entry screen with all of the fields in the current file. It will indicate the proposed new record number of this entry at the top of the form. Type in the data you wish to enter for each field using the UP and DOWN cursor keys to move from field to field. - 7 - If a file has a substantial number of fields, then all of the fields may not fit on one data entry screen. In this case, the word *MORE* will appear in the bottom right corner of the screen. When you complete entry of data on the first screen, then a second screen with the remaining fields will appear. Saving a new entry to the file can be accomplished in several ways. (1) Pressing <ENTER> while the cursor is positioned in the last field of the last data entry screen will save the record. (2) Completely filling the last field with text also will save the record. (3) Pressing CTRL-W will save the new record without displaying the remaining data entry screens if the record requires more than one screen for data entry. (4) Pressing <PgDn> in the last data entry screen of a record will also SAVE the record. Aborting a new entry can be accomplished by pressing the <ESC>ape key at any time before any of the SAVE methods outlined above occur. <PgUp> also aborts data entry in ADD mode only. WAMPUM supports updating of Memo fields in a slightly different way than dBASE III. If you wish to display or edit a memo field, then first move the cursor to that field. It will be displayed on the screen with the field name followed by *MEMO*. Note that memo fields in WAMPUM appear to be logicial fields which can accept True, False, Yes, or No as entries. If you wish to edit the memo field, simply set the logical field to True or Yes by entering a T or Y. When you complete entry of data for this record and execute a SAVE using one of the methods outlined above, the Memo editor will display any memo field marked True and allow you to update it as desired. You then can either SAVE the updated Memo text by pressing Ctrl-W or ABORT the update and leave the Memo text as it was by pressing <ESC>ape. After you ADD a new entry to the file, WAMPUM will display another blank data entry screen thereby allowing you to add another entry. If you do not wish to add another entry, simply press the <ESC>ape key to exit to the Main System Menu. 2.3 E - EDITing Records To edit records in any data base, that file must first be selected and cannot be empty. Look at the bottom of the WAMPUM Main Menu to make sure that the file you want to use is already selected. If not, it can be selected using the F - File Select option in developer mode only. If the file you wish to work with is selected, then you should also consider whether there are indexes which you want automatically updated as you EDIT records in the file. If so, then these, too, must be selected before you EDIT any records. You can determine which indexes are in use by looking at the bottom of the Main System Menu screen. New indexes can be created and/or opened using the I - Index Sel/Create option in developer mode only. - 8 - Once you are working with the correct file and indexes, then EDITing records is as simple as highlighting the E - Edit Record option and pressing <ENTER>. Or you may simply type an E while the Main System Menu is displayed. If you are not using indexes in conjunction with the file being edited, then you will be prompted for the record number of the record you wish to edit. Simply type in the number desired and press the <ENTER> key. If you are using one or more indexes in conjunction with the file being edited, then the first index displayed at the bottom of the Main System Menu is considered the LEAD INDEX and will be used to retrieve records. If this is not the index you wish to use for record retrieval, see the section on Select Utilities for information on how to change the lead index. When editing with an index, you will be prompted to enter a value for the field which is currently the LEAD INDEX. With character fields, you may enter all or part of a key, and WAMPUM will search for a match on the portion of the key entered. With other types of fields, you must enter the exact key to find. Note that capitalization is critical in finding matches. If a LASTNAME field in your data base contains an entry of SMITH and you enter Smith as the key, then WAMPUM will not find the SMITH you are looking for. Once you have entered either a record number or the key of the record to find, WAMPUM will search for the first match. Assuming your application allows duplicate keys, there may be more than one match on a particular key, e.g. there may be a number of Smith's in your data base. If the first data entry screen displayed is not the Smith desired, then <PgDn> through the records until the correct record is retrieved. If you are using a data base with too many fields to fit on one screen, then you may have to <PgDn> several times just to move to the next record. There currently is no key which can be pressed to SKIP to the next record without first displaying all of the edit screens for the current record. If you skip past the record desired, you can also back up through the file in the order of the current key by pressing the <PgUp> key at any time. Once the record is displayed which you desire to EDIT, move to the fields to be edited using the UP and DOWN cursor keys. You can change existing data for a field in several ways. (1) You may type over the existing data. (2) Or you may delete the existing data by pressing CTRL-Y and then enter the new data. (3) Or you may INSERT new data into a field by positioning the cursor where you want the insert to begin. Then press the <INS>ert key. - 9 - With multi-screen records, you can move forward to the next screen by pressing <PgDn>. You cannot move backward within a record by pressing <PgUp>. <PgUp> will save the record and move you to the previous record in the data base. As was true with ADD mode, you can edit Memo fields by marking them True or Yes and then SAVing the record. Similarly, you SAVE edited records in the same way that you do in ADD mode except that <PgUp> also executes a SAVE in EDIT mode and moves you back one record. CTRL-W saves the current record and prompts you for the next record to find. <PgDn> saves the current record and then displays the next record in the file for editing. You can abort any EDIT by pressing <ESC>ape before any of the SAVE actions outlined above occur. If you attempt to find a record which does not exist in the data base, WAMPUM will display an error message and beep at you. You then will be prompted to enter a key of another record to find. When you have searched for all the records desired, press <ESC>ape to exit to the Main System Menu. 2.4 D - DISPLAYing Records To display records in any data base, that file must first be selected and cannot be empty. Look at the bottom of the WAMPUM Main Menu to make sure that the file you want to use is already selected. If not, it can be selected using the F - File Select option in developer mode only. If the file you wish to work with is selected, then you should also consider whether there is an index which you want to use for record retrieval. If so, then this index must be selected as the lead index before you DISPLAY any records. Once you are working with the correct file and index, then DISPLAYing records is as simple as highlighting the D - Display Record option and pressing <ENTER>. Or you may simply type a D while the Main System Menu is displayed. If you are not using indexes in conjunction with the file being displayed, then you will be prompted for the record number of the record you wish to display. Simply type in the number desired and press the <ENTER> key. If you are using an index in conjunction with the file being displayed, then the first index displayed at the bottom of the Main System Menu is considered the LEAD INDEX and will be used to retrieve records. If this is not the index you wish to use for record retrieval, see the section on Select Utilities. When displaying with an index, you will be prompted to enter a value for the field which is currently the LEAD INDEX. You may enter all or part of a key, and WAMPUM will search for a match on the portion of the key entered. Note that capitalization is - 10 - critical in finding matches. If a LASTNAME field in your data base contains an entry of SMITH and you enter Smith as the key, then WAMPUM will not find the SMITH you are looking for. Once you have entered either a record number or the key of the record to find, WAMPUM will search for the first match. Assuming your application allows duplicate keys, there may be more than one match on a particular key, e.g. there may be a number of Smith's in your data base. If the first data entry screen displayed is not the Smith desired, then <PgDn> through the records until the correct record is retrieved. If you are using a data base with too many fields to fit on one screen, then each time you press <PgDn>, WAMPUM will skip to the next record. It will NOT display the subsequent fields of the current record as is the case in EDIT mode. If you wish to look at the subsequent fields of the current record, then press the <ENTER> key rather than <PgDn>. In addition, if there are MEMO fields in the data base with which you are working, these fields will show T if there is an entry in the field. Otherwise, the field will be marked F. To display the first screen of information in any MEMO field, just press <RETURN> rather than <PgDn> on the last screen of the display of the standard fields. If you need to look at the entire contents of of a MEMO field rather than just the first screen, then you must use Edit mode. If you skip past the record desired, you can also back up through the file in the order of the current key by pressing the <PgUp> key at any time. You can abort any DISPLAY by pressing <ESC>ape key. If you attempt to find a record which does not exist in the data base, WAMPUM will beep at you and prompt for another record to find. When you have displayed all the records desired, press <ESC>ape to exit to the Main System Menu. 2.5 M - MARKing a Record for Deletion To mark records as deleted in any data base, that file must first be selected and cannot be empty. Look at the bottom of the WAMPUM Main Menu to make sure that the file you want to use is already selected. If not, it can be selected using the F - File Select option in developer mode only. If the file you wish to work with is selected, then you should also consider whether there is an index which you want to use for record retrieval. If so, then this index must be selected as the lead index before you attempt to DELETE any records. Once you are working with the correct file and index, then marking records DELETED is as simple as highlighting the M - Mark Record *DEL* option and pressing <ENTER>. Or you may simply type an M while the Main System Menu is deleteed. - 11 - If you are not using indexes in conjunction with the file, then you will be prompted for the record number of the record you wish to mark deleted. Simply type in the number desired and press the <ENTER> key. If you are using an index in conjunction with the file, then the first index displayed at the bottom of the Main System Menu is considered the LEAD INDEX and will be used to retrieve records. If this is not the index you wish to use for record retrieval, see the section on Select Utilities. When using an index, you will be prompted to enter a value for the field which is currently the LEAD INDEX. You may enter all or part of a key, and WAMPUM will search for a match on the portion of the key entered. Note that capitalization is critical in finding matches. If a LASTNAME field in your data base contains an entry of SMITH and you enter Smith as the key, then WAMPUM will not find the SMITH you are looking for. Once you have entered either a record number or the key of the record to find, WAMPUM will search for the first match. Assuming your application allows duplicate keys, there may be more than one match on a particular key, e.g. there may be a number of Smith's in your data base. If the first entry displayed is not the Smith desired, then <PgDn> through the records until the correct record is retrieved. If you are using a data base with too many fields to fit on one screen, note that WAMPUM will only display the first screen of data for each record while in DELETE mode. If you skip past the record desired, you can also back up through the file in the order of the current key by pressing the <PgUp> key at any time. Once you find the record you wish to mark DELETED, then answer the DELETE prompt by entering a T for True or Y for Yes, and the record will be marked deleted. You can abort any search by pressing <ESC>ape key. If you attempt to find a record which does not exist in the data base, WAMPUM will beep at you and prompt for another record to find. When you have deleted all the records desired, press <ESC>ape to exit to the Main System Menu. NOTE: WAMPUM uses the same conventions as dBASE III insofar as deleted records are concerned. Deleted records are not really deleted. They are simply marked with an asterisk (*) in the first record position which signifies that they will be deleted the next time the file is rebuilt using the X - REBUILD/FileFix option. At any time before you rebuild the file, any record marked as deleted can be restored using U - UN*DEL* records. The - 12 - primary significance of marking records for deletion is that they will not ordinarily print out when reports, labels, or form letters are produced. Do NOT mark records as DELETED as a means of maintaining a historical data base! The first time a power failure occurs, you may be forced to rebuild a file or index which automatically and permanently deletes ALL records marked for deletion. A better approach is to add a field to your data base which can be used to mark records as inactive or closed. Sometimes it is desirable to be able to mark a group of records as deleted in one pass rather than having to call up each record and mark it for deletion individually. If you start WAMPUM with the developer's password, you may do this IF all of the following conditions are met. (1) The file must be indexed on a character field and that field must be the current (first) index. (2) Record selection criteria must have been specified using S - Select Utilities. It is a very good idea to get a listing of records meeting the criteria BEFORE actually marking the records *DELETED*! (3) Pick the M - Mark Records *DEL* option and when prompted for the value to find, type an asterisk and press <ENTER>. (4) You will be warned one last time that the selected group of records are about to be marked *DELETED*. Type Y to proceed. 2.6 U - UNDELETing a Record To undelete records marked as deleted in any data base, that file must first be selected and cannot be empty. Look at the bottom of the WAMPUM Main Menu to make sure that the file you want to use is already selected. If not, it can be selected using the F - File Select option in developer mode only. If the file you wish to work with is selected, then you should also consider whether there is an index which you want to use for record retrieval. If so, then this index must be selected as the lead index before you attempt to UNDELETE any records. Once you are working with the correct file and index, then marking records UNDELETED is as simple as highlighting the U - UN*DEL* Records option and pressing <ENTER>. Or you may simply type a U while the Main System Menu is deleteed. - 13 - If you are not using indexes in conjunction with the file, then you will be prompted for the record number of the record you wish to undelete. Simply type in the number desired and press the <ENTER> key. If you are using an index in conjunction with the file, then the first index displayed at the bottom of the Main System Menu is considered the LEAD INDEX and will be used to retrieve records. If this is not the index you wish to use for record retrieval, see the section on Select Utilities. When using an index, you will be prompted to enter a value for the field which is currently the LEAD INDEX. You may enter all or part of a key, and WAMPUM will search for a match on the portion of the key entered. Note that capitalization is critical in finding matches. If a LASTNAME field in your data base contains an entry of SMITH and you enter Smith as the key, then WAMPUM will not find the SMITH you are looking for. Once you have entered either a record number or the key of the record to find, WAMPUM will search for the first match. Assuming your application allows duplicate keys, there may be more than one match on a particular key, e.g. there may be a number of Smith's in your data base. If the first entry displayed is not the Smith desired, then <PgDn> through the records until the correct record is retrieved. If you are using a data base with too many fields to fit on one screen, note that WAMPUM will only display the first screen of data for each record while in UNDELETE mode. If you skip past the record desired, you can also back up through the file in the order of the current key by pressing the <PgUp> key at any time. Once you find the record you wish to UNDELETE, then answer the restore prompt by entering a T for True or Y for Yes, and the record will be restored to the data base as an active record. You can abort any search by pressing <ESC>ape key. If you attempt to find a record which does not exist in the data base, WAMPUM will beep at you and prompt for another record to find. When you have undeleted all the records desired, press <ESC>ape to exit to the Main System Menu. NOTE: WAMPUM uses the same conventions as dBASE III insofar as deleted records are concerned. Deleted records are not really deleted. They are simply marked with an asterisk (*) in the first record position which signifies that they will be deleted the next time the file is rebuilt using the X - REBUILD/FileFix option. At any time before you rebuild the file, any record marked as deleted can be restored using U - UN*DEL* records. The down side of this is that once the X option has been run on a file, you can no longer UNDELETE records marked for deletion since they have been permanently deleted from the data base. - 14 - Sometimes it is desirable to be able to undelete a group of records in one pass rather than having to call up each record and restore it individually. If you start WAMPUM with the developer's password, you may do this IF all of the following conditions are met. (1) The file must be indexed on a character field and that field must be the current (first) index. (2) Record selection criteria must have been specified using S - Select Utilities. It is a very good idea to get a listing of records meeting the criteria BEFORE actually restoring the records! (3) Pick the U - UN*DEL* Records option and when prompted for the value to find, type an asterisk and press <ENTER>. (4) You will be warned one last time that the selected group of records are about to be restored. Type Y to proceed. 2.7 P - PRINTing Records To print individual records from any data base, that file must first be selected and cannot be empty. Look at the bottom of the WAMPUM Main Menu to make sure that the file you want to use has already been selected. If not, it can be selected using the F - File Select option in developer mode only. Also make certain that WAMPUM is configured to match the printer you currently are using. This can be changed by selecting the # - PRINTER Config option in developer mode only. If no printer has been selected, WAMPUM will print in generic mode, meaning it outputs pure ASCII text. If the file you wish to work with is selected, then you should also consider whether there is an index which you want to use for record retrieval. If so, then this index must be selected as the lead index before you PRINT any records. Once you are working with the correct file and index, then PRINTing records is as simple as highlighting the P - Print Record(s) option and pressing <ENTER>. Or you may simply type a P while the Main System Menu is displayed. If you are not using indexes in conjunction with the file, then you will be prompted for the record number of the record you wish to retrieve. Simply type in the number desired and press the <ENTER> key. - 15 - If you are using an index in conjunction with the file, then the first index displayed at the bottom of the Main System Menu is considered the LEAD INDEX and will be used to retrieve records. If this is not the index you wish to use for record retrieval, see the section on Select Utilities. When printing records with index retrieval, you will be prompted to enter a value for the field which is currently the LEAD INDEX. You may enter all or part of a key, and WAMPUM will search for a match on the portion of the key entered. Note that capitalization is critical in finding matches. If a LASTNAME field in your data base contains an entry of SMITH and you enter Smith as the key, then WAMPUM will not find the SMITH you are looking for. Once you have entered either a record number or the key of the record to find, WAMPUM will search for the first match. Assuming your application allows duplicate keys, there may be more than one match on a particular key, e.g. there may be a number of Smith's in your data base. If the screen displayed is not the Smith desired, then <PgDn> through the records until the correct record is retrieved. If you are using a data base with too many fields to fit on one screen, then only as many fields as will fit on a single screen will be displayed. To get a print out of the entire record displayed plus the contents of any MEMO fields, answer the Print Record? prompt by typing a T or Y. Make certain that your printer is turned ON and is ON LINE. If you skip past the record desired, you can also back up through the file in the order of the current key by pressing the <PgUp> key at any time. You can abort a PRINT records session by pressing the <ESC>ape key. If you attempt to find a record which does not exist in the data base, WAMPUM will beep at you and prompt for another record to find. When you have printed all the records desired, press <ESC>ape to exit to the Main System Menu. 2.8 X - REBUILD/FileFix Computers are very temperamental when it comes to electricity. Power fluctuations will cause all sorts of undesired results when working with any data base. In network environments, power is even more critical. WAMPUM provides the X- REBUILD/FileFix option as a tool to assist in rebuilding data bases and indexes which typically have been corrupted by power problems. This option obviously does not take the place of a reliable source of electricity. If you are having to use this option frequently, then you should seriously consider an uninterruptible power supply if you value your data! This option now provides three features to assist in file maintenance: (1) - 16 - data base file packing which automatically rebuilds active indexes as well, (2) memo file packing which compresses free-form text entered into memo fields, and (3) reindexing which rebuilds index files associated with a data base. (1) The file packing option rebuilds the entire data base file and resets the end-of-file pointer which oftentimes is damaged by a power outage. If there are active indexes, these are reindexed as well. Be forewarned that this option automatically and permanently DELETES any records marked for deletion. Make certain that you have UNDELETED any records you wish to preserve before executing the file rebuild option! (2) Memo file packing is NOT included in the dBASE file packing algorithm hence packing a data base file does not affect the memo file at all. For those new to the world of dBASE, you should be aware that any time a data base is created which includes one or more memo fields, a separate file automatically is created to store the contents of these fields. It has the same file name as the main data base; however, the file extension is .DBT. As you add data to memo fields, the actual text is stored in the .DBT file while a pointer (an address) is stored in the actual data base file itself. Virtually any time a memo field is revised and expanded even slightly, the entire contents of that memo field is rewritten to the end of the .DBT file, and the pointer is adjusted accordingly. Over time, the size of the .DBT file grows geometrically depending upon how often your memo fields are revised. Previous copies of memo fields are never deleted from the .DBT file. They merely occupy space. To delete them, you must actually execute a dBASE COPY of the data base and then rename the file back to the original name. WAMPUM's memo file packing option does this for you automatically. Before executing this option, always make a backup of your original data base including the .DBT memo file. Also make certain that your default drive has adequate space to house a temporary duplicate of both the .DBF and .DBT files which will be copied and then renamed! (3) Reindexing is a tool which oftentimes will cure damage from power problems without actually rebuilding the data base itself. The principal advantage to reindexing rather than file packing is that it does not delete records marked for deletion in the main data base. If this is a concern, you may wish to try this option to repair damage before choosing file packing. If you do select the file packing, reindexing is performed without selecting this option. 2.9 S - SELECT Utilities 2.9.1 Overview The Select Utilities option in WAMPUM provides end-user access to the two most critical elements in extracting data from a data base: record selection and sorting. Sorting in WAMPUM is - 17 - handled through changing the lead index. Thus, the Select Utilities option also provides the means for setting the primary index for record retrieval purposes. Four other dBASE III functions are provided through the Select Utilities option: LIST FILE CONTENTS, to generate quick report listings with up to 9 fields; CHANGE DATA ENTRY MENUS, which allows a user to select from up to 10 different data entry menus; and BROWSE MODE, to scan through a group of records; and LIST STRUCTURE, which displays or prints a listing of the field structure of the data base file in use. No User's Guide can do justice to the topic of Boolean logic which is record selection in both WAMPUM and dBASE III. There are numerous books including a number of dBASE III primers which cover record selection in much more detail than what is addressed here. Many are available without charge through your public library. For anyone to get the most out of WAMPUM, you must master record selection since it is the critical element in identifying which records should and should not be extracted in reports, labels, and form letters. 2.9.2 Record Selection Criteria Record Selection, which is the dBASE implementation of Boolean logic, is the process by which you tell the computer which records should and should not be extracted in producing reports, labels, and form letters. With the exception of logical fields, the syntax for record selection typically is FIELDNAME relational operator VALUE. The syntax for logical fields is simpler. Assuming a logical field exists in your data base called MARRIED, if you want to find all the records in which the MARRIED field is True, the Boolean expression is simply the field name itself: MARRIED. If you want to find all those in which the MARRIED field is False, the correct expression is .NOT. MARRIED. Any record selection expression can be linked to another expression with one of two connectors: .AND. or .OR. The other cardinal rule is that expressions on both sides of the relational operator must be of the same type. Thus, if a field is a character field then the value must be a character string. If the field is a date field, then the value must be a date. Finally, unlike dBASE III, memo fields can be searched for matches using record selection and should be treated as if they were character fields, i.e. enclose the search values in quotes just as you would a charcter string! Whenever you run a report, label, or form letter, WAMPUM always checks to see if Record Selection Criteria are in effect. If so, it scans the data base for records whose field entries are TRUE when evaluated against the complete Record Selection Criteria then in effect. - 18 - WAMPUM currently supports eight relational operators: OPERATOR MEANING = Equals; matches; begins with. <> Not equals. > Greater than; more than. >= Greater than or equal; at least. < Less than. <= Less than or equal; at most. $ Is contained in. .NOT. $ Is not contained in. The best way to master record selection is by reviewing some examples and finding one that closely matches what you want to do. For this purpose, let us assume that you are working with a data base with the following file structure: FIELD NAME FIELD TYPE FIELD LEN FIELD DEC LASTNAME C 20 0 ACCTNO N 5 0 ENTRYDT D 8 0 MARRIED L 1 0 COMMENTS M 10 0 Now let us assume that there are three records in the file with the following values: FIELD NAME RECORD #1 RECORD #2 RECORD #3 LASTNAME Mundy Johns Johnston ACCTNO 12345 1234 123 ENTRYDT 10/01/85 10/31/85 11/01/85 MARRIED .T. .F. .F. COMMENTS None None None What follows are a number of examples showing the correct record selection syntax, what the expression means in plain English, and which records would be selected by the expression. Criteria: LAST NAME = Johns English: Find all entries where the last name is Johns. Selected: No records. Comments: Not only will no records be selected but WAMPUM will display a System Error forcing termination of the program by typing Q. FIELD NAMES are words of art which must be spelled exactly as they appear in the data base structure. While LAST NAME is fine for English, WAMPUM doesn't know LAST NAME from the MOON. The correct field name is LASTNAME with no spaces! Since LASTNAME is a character field, the value also must be a character string which means it must be enclosed in quotation marks. Either error would have triggered a System Error. Currently, there is no way - 19 - to check for correct syntax before you actually run a report, label, or form letter. Then it's too late! Criteria: LASTNAME="Johns" English: Find all entries where the LASTNAME begins with Johns. Selected: Records 2 and 3. Comments: Note that EQUALS is not pure equivalency in WAMPUM, but more accurately means "begins with." If you want exact equivalence, fill out the field with enough spaces to assure that the match will force equivalence, e.g. LASTNAME="Johns " would select only Record 2. Criteria: LASTNAME="Johns" .AND. ACCTNO=123 English: Find all entries where LASTNAME begins with Johns AND the account number is 123. Selected: Record 3. Comments: For every rule, there is an exception. Equals means exactly equals with numeric fields. Here the account number is numeric while the LASTNAME field is not. Note that BOTH expressions must be true for a record to qualify since the expressions are joined with .AND. Note also that the character string value must be in quotes to match the character field LASTNAME while the numeric value is NOT in quotes to match the numeric field ACCTNO. Criteria: LASTNAME="Mundy" .AND. LASTNAME="Johns" English: Find all entries where LASTNAME is Mundy and Johns. Selected: No records. Comments: Pure English will sometimes get you into trouble. A common beginner's mistake is to mix up .AND. and .OR. Remember: .AND. means BOTH expressions must be True. .OR. means if EITHER is True. Here, no one has a LASTNAME of Mundy AND Johns. All entries have a LASTNAME of Mundy OR Johns. Criteria: MARRIED .OR. LASTNAME="Johns " English: Find all entries where person is married or LASTNAME is equal to Johns. Selected: Records 1 and 2. Comments: When expressions are joined by .OR. then if either expression is true, the record qualifies. Thus, record 1 qualified because the MARRIED field is True and record 2 qualified because of the LASTNAME match. Criteria: .NOT. MARRIED .AND. ENTRYDT>=CTOD("10/31/86") English: Find all the unmarried people with an entry date of at least October 31, 1986. Selected: Records 2 and 3. Comments: The connecter is .AND. so both expressions must be true. Since the MARRIED field is false in both record 2 and 3 and since the ENTRYDT is at least 10/31/86, they both would be output. Note that the VALUE type must match the field type with the DATE field. There is no direct way to enter a date in dBASE. Thus, you must enter the character string "10/31/86" and then - 20 - convert it to a DATE with the character-to-date function: CTOD(). Criteria: ENTRYDT>=CTOD("10/01/86").AND.ENTRYDT<=CTOD("10/31/86") English: Find all of the October, 1986 entries. Selected: Records 1 and 2. Comments: Here we are using a range of dates to select a month's worth of entries. Note that spacing between text is optional. Both expressions must be true for a match. DATE fields must have DATE values. CTOD() does it. Criteria: "This is a test"$COMMENTS English: Find every record in which the text "This is a test" appears in the COMMENTS memo field. Selected: Don't know. See below. Comments: The $ operator is one of Boolean logic's most powerful tools since it automatically searches TEXT STRINGS for a match anywhere in the string. It can be especially helpful for use with fields in which a word may appear at any place in a lengthy string of text. For purposes of searches, MEMO fields are treated by WAMPUM as text strings. Thus, you can search ANY memo field with the logic outlined above. To negate the expression, i.e. "This is a test" is NOT contained in the MEMO field, the correct syntax is .NOT."This is a test"$COMMENTS. In this case, we didn't specify the contents of the MEMO field in developing the example. Thus, there is no way to tell if the text was found or not. WAMPUM'S SELECT ASSIST For those experiencing problems in mastering dBASE Boolean syntax but who have mastered Boolean selection theory, WAMPUM provides a helping hand: SELECT ASSIST. By entering an asterisk (*) as the first character in the Record Selection field or whenever you pick the LIST FILE CONTENTS option when no selection criteria are in effect, SELECT ASSIST springs in to action. SELECT ASSIST is a menu-driven record selection tool similar to that found in many data base systems such as dBASE III Plus. It permits a user to enter up to 10 record selection criteria using a 4-step menu process. As indicated earlier, it cannot replace the human brain in figuring out which records you want to work with, but it can help you master dBASE selection syntax. FIELDNAME SELECTION Once SELECT ASSIST is started, it will display a screen with the name of the first field in the active data base. Step 1 is to identify the field involved in making your selection of records. If you don't remember the field names in the data base, simply press the <Dn> and <Up> cursor keys to "thumb through" the field names. When you find the one you want, press <ENTER>. - 21 - If you already know the field name and there are a lot of them in your database, you may find it more convenient just to type several of the beginning characters of the field name. SELECT ASSIST will begin searching for a matching field name as soon as you type a letter between A and Z. If it finds no match, it will beep and redisplay the first field name in the data base. Since several fields obviously can have the same beginning letters, you may have to type several letters of the field name for SELECT ASSIST to find the field you're looking for. Once the field name appears that you want, press <ENTER> to continue. It should be noted that once you have pressed <ENTER>, it is too late to change your mind about any previous selection you have made. If you have made a mistake, your only option is to start over by pressing <ESC>ape to exit. HINT: Be sure of your choice before you press the <ENTER> key! If you do ESCape from SELECT ASSIST, you also will need to ESCape from the LIST FIELDS screen if you picked LIST FILE CONTENTS. Otherwise, your list will include data on all records in your data base. RELATIONAL OPERATOR SELECTION After selecting a field name, you then must choose a RELATIONAL OPERATOR telling WAMPUM what sort of comparison you wish to make against this field. The default is EQUALS. You may "thumb through" the choices by pressing the <Dn> or <Up> cursor keys. Depending upon the field type of the field name specified, the relational operator selections will vary. Display the operator desired, then press <ENTER> to proceed. VALUE SPECIFICATION Once you have specified the relational operator, you next must tell SELECT ASSIST what VALUE for this field you want to find. Again, depending upon the field type, your options in specifying a value may be limited. For example, if the field is a date field, the VALUE must also be a date. With a logical field, there is no value specification. Character fields require the entry of text without surrounding quotation marks. Press the <ENTER> key once you have specified the value desired. CONNECTOR SELECTION Connector selection allows you to indicate how this selection should be linked to the next selection, if any. The choices are listed by using the <Dn> and <Up> cursor keys. You may choose AND, OR, or NO CONNECTOR. If you choose NO CONNEC- TOR, SELECT ASSIST assumes you are finished. Specifying either of the other choices by pressing <ENTER> takes you to the next line to enter a second selection criteria beginning with another field name. - 22 - Once you have entered all of the selection criteria desired, press the <PgDn> key in the CONNECTOR SELECTION field to tell SELECT ASSIST you are finished. You may also specify NO CONNEC- TOR and press <ENTER> which has the same effect. If you accidentally press <ENTER> to move to the next line with a connector of AND or OR, you may still end processing of SELECT ASSIST by pressing the <PgDn> key in the FIELD NAME position. In this case, SELECT ASSIST assumes you wanted to use only those selection criteria on the lines above the current line. 2.9.3 Listing File Contents Many times there is a need to produce a "quick and dirty" report which lists certain fields of information on a certain group of records in the data base. The List File Contents option in conjunction with a previously specified Record Selection Criteria satisfies this need by simulating the dBASE LIST command. If the List File Contents option is marked True, WAMPUM first will display the SELECT ASSISTANT previously described if no record selection criteria are in effect. After specifying record selection criteria, WAMPUM then will display a screen asking the user to identify the fields to be listed. The user should type a number between 1 and 9 beside each field which should be listed. No number can be used twice! If a MEMO field is to be included in the listing, it should be the field with either the highest or lowest number to assure that it prints in either the far right column or the far left column of the listing. Pressing <PgDn> moves the user to a screen which prompts for (1) whether to print the listing, (2) whether to output all records (i.e., override record selection criteria then in effect), and (3) whether to output records marked for deletion. When these prompts are answered, WAMPUM will produce the list with field headings either on the screen or on the printer. If the total width of the fields specified for the listing exceeds the screen width or current printer width, the listing will be wrapped to the next line. At the end of the listing will be a summary of the record selection criteria then in effect. 2.9.4 Changing Current Data Entry Menu In addition to its standard data entry menu, WAMPUM provides the capacity for creating up to 9 customized data entry menus to match different data entry stages for any given application. The number of menus available to the end-user are specified by the developer in creating an application. You may change data entry menus at any time by following these simple steps. Access the S - Select Utilities screen from the Main System Menu. Change the Change Current Menu field to T and press <PgDn>. A listing of the available menus will be - 23 - displayed. Simply type the number corresponding to the menu you want to use. You then will be returned to the Main System Menu. Until you change menus again, this new data entry menu will appear whenever you Add, Edit, or Display Records. 2.9.5 Picking the Lead Index Files can only be accessed and output can only be produced in the order of one index at a time even though WAMPUM automatically updates up to 7indexes as you add and modify entries in the file. The LEAD INDEX is always the FIRST index displayed at the bottom of the WAMPUM Main System Menu. If you want to retrieve records in some order other than what the current LEAD INDEX would provide, then you can change the LEAD INDEX. Similarly, all output from WAMPUM including REPORTS, LABELS, and FORM LETTERS is produced in the order of the LEAD INDEX. If you want the output ordered differently, then you must change the LEAD INDEX before generating the report, labels, or form letters unless you are using the W - WAMPUM PreFormat option. To change the LEAD INDEX, select the S - Select Utilities option from the Main System Menu by typing an S or highlighting the option and pressing the <ENTER> key. Enter any selection criteria desired then press <ENTER> to move to the field which asks Change Lead Index. Change the value of the field from False to True by typing either a T or Y. Assuming you have more than one index in use, a list of available indexes then will be displayed. Just enter the number of the one which you want to designate as the LEAD INDEX. Always remember to check the LEAD INDEX before producing output from your file to assure that it is set as you desire. 2.9.6 Setting Browse Mode ON WAMPUM implements dBASE III's powerful BROWSE command in a slightly different way. By setting BROWSE Mode ON by specifying T or Y to the prompt in the Select Utilities screen, WAMPUM uses a two-step process for EDITing, DISPLAYing, DELETing, and UNDELETing records. The user first will be prompted for the key field value to find. Then, instead of the usual data entry display, the user first will be presented with a table of the first twenty records in key order beginning with the first matching key value. WAMPUM displays as many fields from the data base for each record as will fit on a single line of the screen. Within this display, the user can move UP and DOWN through the records with the UP and DOWN cursor keys. The user can request the next twenty records beginning with the last record - 24 - currently displayed by pressing the <PgDn> key. Browse also permits the user to move UP a single record by pressing <PgUp>. If the record is found for which you are searching, then simply highlight that option and press the <ENTER> key. This then triggers the usual WAMPUM data entry screen. If no record is found for which you desire to move to the full data entry screen, then two choices are available. Pressing <ESC> will ABORT the BROWSE session and return you to the Main System Menu. Pressing the <SPACE BAR> or any other key not previously mentioned will allow you to enter a new record key value and commence another search. BROWSE mode is particularly useful in situations in which there may be multiple entries with a similar key value, i.e. a number of entries with a LASTNAME of Smith. BROWSE permits you to examine the partial contents of 20 records at a time in order to identify the exact record with which to work. Note that you cannot actually change any data while in the BROWSE mode. You must move to the actual data entry screen to do this. If a record has been marked for deletion, that entry will show an asterisk (*) as the first character of the line. Otherwise, the first character position is always blank. Once the full data entry mode has been triggered by pressing the <ENTER> key, the user still has the ability to move through the data base with either <PgDn> or <PgUp>. At this juncture, it is necessary to return to the Main System Menu before the BROWSE mode is reinitiated. 2.9.7 Listing the File Structure Particularly in developing reports, labels, and form letters, it is helpful to have a listing of the structure of the data base file in use. The last option on the Select Utilities screen permits a user to request this listing. If the prompt is answered with Y or T, then WAMPUM will ask whether you want the listing printed as opposed to displayed. Typing T or Y at the Printed? option will provide a printed listing. Pressing <ESC> will abort the listing entirely. Pressing <PgDn> or <ENTER> will display the file structure on the screen. 2.10 R - REPORTS Generation The R - Reports option allows you to run existing dBASE III report formats and create new ones. Creation of new reports is covered in the Developer's section of this User's Guide. Before selecting the Reports option, you already should have used the Select Utilities option to enter Record Selection Criteria and to specify the Lead Index for report output. If you did not do so, simply press <ESC>ape to return to the Main Menu. - 25 - When you select the Reports option, a listing of report forms in the default directory will be displayed. You then are prompted to enter the name of the report form you wish to run. Type in the file name EXACTLY as it appears in the directory listing. Do NOT include the .FRM file extension. There also is a field which allows you to specify the PRINTER FONT to be used if the report is to be printed. If a report is to be printed on regular 8-1/2 x 11 inch paper using 10 pitch type, then NO font number needs to be entered. If your printer supports smaller fonts thereby enabling production of wider reports or reports turned sideways, enter a number corresponding to the font desired. See the # - Printer Config section of the Developer's section of this User's Guide for more information. Once you have entered a font or pressed the <ENTER> key, the Printer Selection Screen will appear. It permits you to specify (1) whether to Print or Display the Report, (2) whether to override the Record Selection Criteria and output ALL records, and (3) whether to output records marked for deletion which typically are not output. See the Printer Selection Screen section of this User's Guide for more information on these options. 2.11 L - LABELS Production The L - Labels option allows you to run existing dBASE III label formats and create new ones. Creation of new labels is covered in the Developer's section of this User's Guide. Before selecting the Labels option, you already should have used the Select Utilities option to enter Record Selection Criteria and to specify the Lead Index for label output. If you did not do so, simply press <ESC>ape to return to the Main Menu. When you select the Labels option, a listing of label forms in the default directory will be displayed. You then are prompted to enter the name of the label form you wish to run. Type in the file name EXACTLY as it appears in the directory listing. Do NOT include the .LBL file extension. There also is a field which allows you to specify the PRINTER FONT to be used if the labels are to be printed. If the labels are to be printed using standard 10 pitch type, then NO font number needs to be entered. If you will be producing labels on a laser printer, then FONT 7 should be selected. See the # - Printer Config section of the Developer's section of this User's Guide for more information. Once you have entered a font or pressed the <ENTER> key, the Printer Selection Screen will appear. It permits you to specify whether to Print or Display the Labels, whether to override the Record Selection Criteria and output ALL records, and whether to - 26 - output labels for records marked for deletion. These typically are not output. See the Printer Selection Screen section of this User's Guide for more information on these options. 2.12 T - FORM LETTER Generation The T - Form Letters option allows you to run existing WAMPUM form letters and create new ones. Creation of new form letters is covered in the Developer's section of this User's Guide. Before selecting the Form Letters option, you already should have used the Select Utilities option to enter Record Selection Criteria and to specify the Lead Index for form letter output. If you did not do so, simply press <ESC>ape to return to the Main Menu. The one exception to this is where you wish to generate a form letter using an indexed key to find a single record. In this case, make certain that no Record Selection Criteria are in effect. Then select the T - Form Letters option. After selecting a form letter file as outlined below, you will be prompted to enter the key value to find using the primary index then in effect. When you select the Form Letters option, a listing of form letter files in the default directory will be displayed. Note that a form letter file is a standard .DBF file except that its file name begins with T-. You then are prompted to enter the name of the form letter form you wish to run. Type in the file name EXACTLY as it appears in the directory listing. Do NOT include the .DBF file extension. There also is a field which allows you to specify the PRINTER FONT to be used if the form letters are to be printed. If the form letters are to be printed using standard 10 pitch type, then NO font number needs to be entered. See the # - Printer Config section of the Developer's section of this User's Guide for more information. Once you have entered a font or pressed the <ENTER> key, the Printer Selection Screen will appear unless there are no record selection criteria in effect. In the latter case, you will be prompted to enter the record key to find using the lead index then in effect. When the printer screen displays, it permits you to specify whether to Print or Display the Form Letters, whether to override the Record Selection Criteria and output ALL records, and whether to output form letters for records marked for deletion. These typically are not output. See the Printer Selection Screen section of this User's Guide for more information on these options. - 27 - 2.13 W - WAMPUM Preformatted Output The WAMPUM Preformatted Output option allows you to run up to 80 predefined Reports, Labels, and Form Letters each with predefined selection criteria, sort order, and even a related file for table lookup if desired. This is perhaps WAMPUM's most powerful feature and is NOT available in dBASE III at all. Before this option is available, the WAMPUM master file must be created and appropriate entries must be made for the pre- defined output desired. This is covered in the Developer's section of this User's Guide. Assuming that this already has been done, then all that is necessary to run WAMPUM Preformatted Output is to select the W - WAMPUM PreFormat option from the Main System Menu. A two-column listing of reports, labels, and form letters available for automatic production then will be displayed. Following the description of each item will be a single letter (R, L, or T) indicating whether the output is a Report, Label, or Form Letter. Mark the reports, labels, and form letters you wish to produce with a T or Y in the logical field provided to indicate which should be run. You will notice at the bottom of the screen a range of dates is specified. The default range of dates is the beginning and ending of the current month unless today's date is less than the 6th of the month. In this case, the default is the beginning and ending dates of last month. Most folks produce monthly reports for a prior month at the beginning of the next month so WAMPUM saves you a little typing. The range of dates can be changed by you to any dates desired although the first date should always be less than or equal to the second date. The range of dates are automatically used for any preformatted reports, labels, or form letters in which the developer wanted the end-user to have the flexibility to select the time period for the report at the time it was produced. For instance, using the data base example outlined earlier to show how to select records, let us suppose that the developer had predefined a report which would output certain information about new entries covering a period of entry dates. If that report were run as a WAMPUM Preformatted Report, you then could specify the range of entry dates at run time rather than the developer constantly having to update the master record. This also frees you from having to master Boolean logic overnight! The only rule to remember is that the DATE RANGE specified applies to ALL output produced during a single run. Thus, if you had two preformatted reports for which you wanted different date ranges on output, then you would have to run one report with one date range. Then select the WAMPUM Preformatted option again, change the date range, and run the other report. - 28 - Once you have entered your choices, the Printer Selection Screen will appear. It permits you to specify (1) whether to Print or Display the output, (2) whether to override the Record Selection Criteria and output ALL records, and (3) whether to generate output for records marked for deletion. These typically are not output. See the Printer Selection Screen section of this User's Guide for more information on these options. 2.14 Printer Selection Screen 2.14.1 Printed Output Whenever you run a Report, Label, Form Letter, or WAMPUM Preformatted Output, you will see the Printer Selection Screen which lets you choose whether to PRINT or DISPLAY the information. If you want the OUTPUT printed, type a T or Y at the prompt. 2.14.2 Output All Records If record selection criteria are in effect, you also will be asked whether you want to override those criteria and OUTPUT information on ALL records in the data base. If you DO want to OVERRIDE the record selection criteria in effect, then change the default entry to T or Y. 2.14.3 Output Records Marked for Deletion You also will be asked whether to output information on records marked for DELETION. The default is No. If you want DELETED records included in your output, change the entry to T or Y. 2.15 On-Line HELP The best way to learn WAMPUM is to read this User's Guide cover to cover. Most folks won't do that so WAMPUM provides some of what is contained in the User's Guide in HELP screens keyed to where you are in the program. To access the HELP screens, press the F1 function key at any time. Depending upon where you are in WAMPUM, a screen of HELP will be displayed. Simply press the <ENTER> key to return to where you were. Every choice from the WAMPUM Main System Menu has an intermediate screen which gives you a chance to change your mind. It is on this second screen after picking any option that - 29 - the most detailed HELP is available. Once you have read the HELP message and returned to where you were, you can return to the Main System Menu simply by pressing the <ESC>ape key. In short, you can get HELP on any WAMPUM topic without actually having to complete execution of that particular function. - 30 - 3 Developer Functions 3.1 Creating A New Application 3.1.1 Overview of Application Development Strategy As with any application development, the best advice in starting a new project is TURN OFF THE COMPUTER and use your head for a while to figure out what you want to do. What data input will you need to capture to get the output desired? Once you know what you want, then some familiarity with WAMPUM's structure will help. WAMPUM is designed to be stored in a directory from which it can be run regardless of the active default directory on your hard disk. This means it should be in a directory supported by the current DOS PATH. The cardinal rule in using WAMPUM is a simple one: separate applications should be created in separate subdirectories which are NOT in the DOS PATH. There are two reasons for this. First, WAMPUM creates a number of supporting files for each application. If you create more than one application in a given subdirectory then these supporting files will not be available for use in both applications. Second, the reason for not building applications in a directory that is part of the DOS PATH is because WAMPUM accesses files on the hard disk using the same PATH command that DOS uses. If you build an application in a directory which is part of the PATH, then WAMPUM's supporting files may unintentionally spill over into other WAMPUM applications as you begin building them. Each WAMPUM application typically will include a main file, perhaps a related file, several indexes, and numerous reports, labels, and forms. In addition, each time you run WAMPUM in a new directory, it automatically builds some supporting files for that application. These include EDIT.DBF (which is used to store the edit checks for a particular application), KEYS.DBF (which is used to store any keyboard macros for a particular application), MENUS.DBF (which is used to store up to 9 data entry screen formats) and, if requested, WAMPUM.DBF (which is used to build a library of preformatted reports, labels, and form letters which can be run without users having to master Boolean logic and sorting rules). For the same reason stressed above, you should not run WAMPUM in a directory which is part of the DOS PATH for it will build these supplemental files which may then inadver- tently spill over into other applications on the hard disk! You may be wondering why anyone would want a DOS PATH if it causes all these problems. The answer is that the DOS PATH gives WAMPUM the capability to share data stored in other directories without having a duplicate copy in the current directory. For example, the printer configuration files can be stored in the same directory as WAMPUM yet they may be used from any directory. Similarly, in certain situations with very large data bases which must be shared by several applications, it may be desirable to move the shared data base itself into a directory which is part - 31 - of the DOS PATH so that it can be used in multiple applications without having to duplicate the data. These are considerations you would want to think through while the computer is turned OFF! What follows in the subsequent sections is the STEP-by-STEP process for building a new WAMPUM application. In order to simplify the presentation, it helps to use a sample application. We will assume that the application to be built is based upon the data base outlined previously. The structure of that file is repeated here for the sake of clarity: FIELD NAME FIELD TYPE FIELD LEN FIELD DEC LASTNAME C 20 0 ACCTNO N 5 0 ENTRYDT D 8 0 MARRIED L 1 0 COMMENTS M 10 0 3.1.2 Create A New SubDirectory The first step in building a new WAMPUM application is to create a new subdirectory on the disk to house the information. You must be at the DOS prompt to perform these steps. We recommend you name the subdirectory using a single word of up to 8 characters in length with no embedded spaces or punctuation. To keep things simple, let's name it SAMPLE here. If you want to follow along, type the following commands. Press the <ENTER> key after typing each command. PROMPT $P$G CD \ MD SAMPLE CD \SAMPLE The commands above (1) change the DOS prompt to assure that you'll know the subdirectory in which you are working, (2) move you to the "root" (top) directory, (3) make a new directory named "SAMPLE", and (4) move you to the new "SAMPLE" directory. If you are working on the C: drive, the prompt on your screen after issuing the above commands should be C:\SAMPLE>. You now are ready to start up WAMPUM. Since you are building a new application, you will want to use DEVELOPER MODE. This means you need to include the developer password as shown below. Unless you need to force WAMPUM into monochrome mode, type the following command and press the <ENTER> key: WAMPUM VOODOO If you have a Compaq or some other clone that reports a color card when you are using a monochrome display, then type: WAMPUM VOODOO MONO - 32 - 3.1.3 Building a New File The first piece of the new application to build is the main data file. This may contain up to 400 fields depending upon the amount of free memory in your computer. Be aware that you will forfeit dBASE III compatibility when you create more than 128. Select the B - Build New File option from the Main System Menu by typing a B or highlight the option and press <ENTER>. You then will be prompted to enter a file name for your new data base file. The file name must comply with DOS requirements for file names, i.e. up to 8 characters, no spaces, and no punctuation. Think of a file name that bears some relationship to the application. It makes things easier. For our sample, let's use ACCOUNTS. Type in the file name and press <ENTER>. Note that you do NOT enter the file extension which WAMPUM assigns as .DBF. You then will be prompted to enter four pieces of infor- mation for each new field in your data base: a FIELD NAME, a FIELD TYPE, a FIELD LENGTH, and FIELD DECIMALS, if any. In determining the order of the fields in the data base being created, keep in mind that BROWSE mode, which was discussed previously under the Select Utilities option, displays a single line of fields for about 20 records at a time. If your users will be using BROWSE mode, then you should select the most important fields in the data base as the first fields in the file. This will assure that they are displayed when the user sets BROWSE mode ON. The actual number of fields which will fit on a single line of the screen is determined by two factors: the length of the field names used and the maximum length of the field data. Adding these lengths together plus a space between each field, WAMPUM will display as many fields as will fit within 79 characters in BROWSE mode. The first character position of the line is reserved to display whether a record has been marked DELETED. Field names should bear some resemblance to the piece of data which will be stored in the field. dBASE III supports 10 character field names, and WAMPUM can use them, too. However, applications are much more straight-forward if field names are limited to 8 characters or less since this length matches the DOS filename length restriction. Field types and lengths supported by WAMPUM include: Field Type Abbrev Min.Len. Max.Len. Comments Character C 1 254 Any text string Numeric N 1 15 Numeric for math Date D 8 8 Any date info Logical L 1 1 True/False info Memo M 10 10 Free-form WP text - 33 - Field decimals will always be 0 except for numeric fields in which you want to use real numbers, i.e. those with decimals. Remember that with such fields, the TOTAL length is the maximim number of integer positions, plus 1 for the decimal, plus the number of decimal positions. Thus, if the largest value to be entered in a numeric field is 999.99, the field length is 6 and decimals is 2. Enter the information for the fields outlined in our sample. After entering all of the fields, a new blank record will appear. Press the <ESC>ape key to indicate that you are finished. 3.1.4 Selecting the New File Once the data base structure has been created, you are ready to tell WAMPUM which file you will be working with. From the Main System Menu select the F - File Select option to place the file in use. When you pick this option, you will be prompted for the name of the file to use. If you forget the name of the file, just press the <ENTER> key and a list of .DBF files in the current directory will be displayed. Press <ENTER> to return to the file name prompt. Type ACCOUNTS as the name of the new file and press <ENTER> to redisplay the Main System Menu. The bottom of the Main System Menu now should show the file in use with a notation: FILE: ACCOUNTS. 3.1.5 Revising the Existing File Structure Beginning with version 3.1, WAMPUM provides a simple facility to revise the structure of an existing data base. This often becomes necessary when you design an initial data base without first turning the machines to spend some time thinking first. To revise the structure of an existing data base, you first must select that file for use with the F - File Select option. Once the file is in use, select the B - Build New File. The prompt will advise you to insert an asterisk (*) for the file name if you desire to revise the existing data base structure. Type an asterisk and press <ENTER>. WAMPUM will ask whether you really want to revise the structure of the data base. Type Y. WAMPUM will display up to two columns of fields from your data base. For each field, you may change the field name, field type, field length, and field decimals. You may also delete a field from the structure by marking the DELETE? option True. If you change the name or field type of an existing field, ALL DATA which exists in that field throughout your data base will be destroyed! If there are more than 40 fields in your data base - 34 - structure, you can move through them using the <PgDn> and <PgUp> keys. Once you have made all the changes to existing fields desired, press the <ESC> key to proceed. WAMPUM then will ask whether you wish to ADD new fields to the existing data base. If you need additional fields, type Y and you will be prompted for a field name, type, length, and decimals entry for each new field. You also can use <PgUp> and <PgDn> to move through the existing fields. Once you have added all of the new fields desired, press <ESC> to proceed. WAMPUM then gives you one last chance to avoid modifying the structure of your data base. If you wish to proceed, type Y when prompted for whether to revise the data base structure. Make certain that your hard disk has sufficient empty space to tempo- rarily house a duplicate of your data base (.DBF) and memo fields file (.DBT), if any. Also make certain that you make a backup of your data base before revising the structure of the file. Once the data base has been revised, always reindex using the X - Rebuild/FileFix option. If you are using edit checks, data entry menus, or keyboard macros which were keyed to the old file structure, make certain that these are revised to reflect the new data base structure before adding or editing data in the data base. 3.1.6 Indexing the New File 3.1.6.1 Overview WAMPUM indexes serve two functions in run-time applications. First, they provide a quick means of retrieving records for edit, display, or printing. Typical retrieval times even with large data bases are less than one second. Indexes also serve as the sorting tool for all output: reports, labels, and form letters. Thus, in building a new application, you need to take both of these considerations into account. You will need indexes to retrieve your data quickly for updating. And you may need other indexes to assure that reports, labels, and form letters are produced in the proper sorted order. The primary advantage in using indexes rather than a sort for output is that no physical sorting of the data base ever takes place since the indexes are constantly updated as new records are added and old ones are modified. This saves an enormous amount of time in producing reports. WAMPUM 3.1 supports up to SEVEN indexes for any application. It should be noted that while these indexes function much like the indexes in dBASE III, they are not compatible. Thus, if you are moving dBASE III applications over to use with WAMPUM, the data base, reports, and labels are compatible, but the indexes are not. These can be rebuilt easily using the guidelines which follow. WAMPUM indexes have a file extension of .NTX. - 35 - Select the I - Index select/create option from the Main System Menu. Notice that this option provides a developer with a means both to create new indexes and to use existing ones. Both avenues are addressed in the next sections of this Guide. 3.1.6.2 Creating New Indexes New indexes can be created in one of two ways depending upon the type of index desired. WAMPUM can create an index of any character, numeric, or date field as it exists in the data base. Or you can create a special index made up of a combination of fields in the data base using dBASE string manipulation functions. For example, if your data base had fields for both a first name and a last name, you might want a single index which sorted the data base on last name and then first name within the last name. The simpler index which is simply a single field index is created by entering a single asterisk (*) in the space provided for the index name. If you wish to create more than one index, enter a single * in the space provided for Index 1, Index 2, etc. When you have entered as many asterisks as desired, press <PgDn> to continue. The screen will then clear, and a list of all the fields in your data base will appear. Mark the name of ONE field you want to index with the letter T or Y. Make certain that you mark only ONE field on the screen True. Then <PgDn> to continue. If you indicated that you wished to create more than one index by putting an * in more than one of the Index spaces, then you will get another screen with the same field list. Mark the next field you want to index with a T or Y, and <PgDn> again. Continue this process until up to 7 indexes have been created. In our example, you probably would want to index two fields: the LASTNAME field and the ACCTNO field. So you should place a single * in the first two Index spaces provided and <PgDn>. In some circumstances, a more complex index may be desired. If you know what you are doing (i.e. you really are a dBASE III programmer), you can build any type of index to achieve any type of sorting desired. To build a more complex index, enter two asterisks (**) beside each Index entry provided and <PgDn>. You then will be prompted to name the new index file and then to enter the index expression. This expression can be ANY legal dBASE III string expression. Note two differences with Clipper's indexes insofar as TRIMmed fields (those with the trailing spaces stripped off) are concerned. If you are trimming spaces off character strings, they must be added as real spaces at the end of the expression. Otherwise, the resultant index will be nothing but a null string. Second, an index expression must have a constant fixed length. For example, if you wanted to index on lastname then comma space first name, the correct syntax is SUBSTR(TRIM(LASTNAME)+", "+FIRSTMI+SPACE(20),1,35). The SPACE(20) expression assumes the LASTNAME field is 20 characters in length. - 36 - 3.1.6.3 Selecting Indexes Once you have built new indexes, they automatically are selected for use in the same order they were built. You can change both the LEAD INDEX and the active indexes at any time by picking the I - Index select/create option and entering the number of the lead index or the names of the indexes desired. One caution is in order. Remember that indexes are only UPDATED with ADD or EDIT if those indexes are in use at the time the file is changed! You can ascertain which indexes are in use by looking at the INDX listing which appears below the Main System Menu. If you built the indexes recommended in the last section, the last line of your screen should read as follows: FILE: ACCOUNTS INDX: LASTNAME,ACCTNO 3.1.7 Printer Configuration (.MEM file) 3.1.7.1 Overview In order to create high-quality output in reports, labels, and form letters, you will need to configure an application for a specific printer. WAMPUM is packaged with several printer configuration tables which already have been built to support a number of popular printers. If you're a lucky person, your work has already been done. If not, read the section on constructing a new printer table below. WAMPUM is designed to allow a developer to imbed printer codes in reports, labels, and form letters to control the actual printing of text. In addition, the end-user can specify the starting printer font to be used to output any report, label, or form letter. Finally, WAMPUM preformatted output includes the option of specifying the initialization printer string. What is a WAMPUM printer table? It is a standard dBASE III memory variable file (.MEM file extension) with special codes that tell your printer to print in a certain mode. The following field names are reserved by WAMPUM and should not be used as field names in your data bases. These fields can be used in creating report forms, labels, and form letters to vary the type styles within those output documents. FONTINIT FONT1 FONT4 FONT7 FONTRESET FONT2 FONT5 FONT8 FONT0 FONT3 FONT6 FONT9 Note that the FONTINIT sequence always gets sent to the printer before anything is printed. The FONTRESET sequence always gets sent after anything is printed. If these fields are empty, then obviously nothing gets sent. - 37 - The default font for all output is FONT0. This always gets sent after the FONTINIT sequence unless you specify some other number when the output is generated. Listed below is the definition logic used to develop the font codes for the HP Laserjet printers. It is similar to what was used for the Epson printers, except all output is in portrait mode with Epson. In general terms, FONT9 is reserved for very small print to accomodate reports wider than 132 columns. FONT8 is reserved to accomodate reports from 81 to 132 columns wide. FONT7 is used with the lasers to get mailing labels to line up. FONT0 10 pitch Courier, portrait mode FONT1 10 pitch standard, portrait mode FONT2 10 pitch bold, portrait mode FONT3 10 pitch italics, portrait mode FONT4 Proportional, big bold, portrait mode FONT5 Proportional, baby print, portrait mode FONT6 Standard, baby print, portrait mode FONT7 10 pitch with codes suitable for LABELS FONT8 10 pitch, standard, landscape mode FONT9 Standard, baby print, landscape mode Obviously, use of these font codes can be adjusted as your application demands. There may be instances in which you need underscoring. This can be accomplished using one font to turn on automatic underscore and another to turn it off if your printer supports it. For those using LaserJet Plus or LaserJet II printers, you should be aware that these font codes also can be used to imbed a logo or signature block in a form. Pricing for digitized logos is about $150 each while digitized signatures cost about $50. One source for these is Orbit Enterprises, P.O. Box 2875, Glen Ellyn, IL 60138. The phone number is 312/469-3405. 3.1.7.2 Selecting an Existing Printer Table To select an existing printer table for use, choose the option labeled # - PRINTER Config on the Main System Menu. A listing of all .MEM files in the current directory will be displayed. Enter the name of the printer table you wish to use without the .MEM file extension. Note that you may use a table which is stored in another directory so long as that directory is part of DOS's PATH command and as long as you know the file name. Once you have selected a printer, the Main System Menu will reappear and the last line on the screen should now show the printer and FONT in use. Assuming you selected the HPLASERA font, the last line of your screen should look like this: FILE: ACCOUNTS INDX:LASTNAME,ACCTNO PRT: HPLASERA/0 - 38 - 3.1.7.3 Creating a New Printer Table If there is no printer table already available for your non- standard printer, then you will need to build one. It's easy! First, select the # - PRINTER config option on the Main Menu. When WAMPUM prompts for the name of the printer table to use, type an asterisk (*) and press <ENTER>. If entering a file name for your new printer template, you then will get a data entry screen in which to type the special codes for your printer. You will need your printer manual to figure these out! First, decide what you want each of the printer fonts to do. You also must determine what sort of initialization sequence, if any, you want to initiate whenever anything is printed. And, you will want to decide whether to reset your printer after the printing is completed. Almost every printer has some code sequence which resets the printer to its default settings just as if the printer had been switched off and on. This is a good idea! It always assures that your printer is configured in a standard way for the next job. It's an equally good idea to execute this reset as part of the printer initiali- zation sequence. Most printer codes start with an <ESC>ape code which has the ASCII value of 27. In a lot of printer manuals, it is referred to as CHR$(27) which is the way <ESC> is written in BASIC. Any time you see a code written as above which cannot be typed using the standard typewriter keyboard, you can enter it in WAMPUM just as you would in LOTUS 1-2-3 or Symphony, i.e. \027 (a backslash followed by a three-digit number representing the ASCII code of the character desired: zero, two, seven). For example, if your printer manual says that ESCAPE E or CHR$(27)+E is the escape sequence to reset your printer, then enter the following: \027E. Particularly with laser printers, it may be desirable in some situations to force some carriage returns at the beginning of a job. This is especially true to line up mailing labels. To accomodate this, WAMPUM permits the developer to insert carriage return codes in the font setups using the tilde (~). One tilde means one return. Two tildes means two returns, etc. Make certain that ALL tildes follow the complete escape sequence you desire to generate for each font code since characters following tildes are ignored. Do NOT use tildes in the FONTINIT, FONTRESET, FONT0, or FONT2 codes since these have special uses in WAMPUM. Use this process to build the printer table for your printer, and you're all set. Press the <PgDn> key when you have entered all of the codes desired. Note that you also can edit an existing printer table by entering an * as if you were creating a new printer table. When WAMPUM prompts for the name of the new printer table, simply enter the name of the old table. When the data entry screen appears, you will see that codes such as \027 have been converted - 39 - by WAMPUM into the actual ASCII character. In the case of the <ESC> code, this is an arrow pointing to the left. These codes can be deleted or edited as desired. A final word of warning. Do NOT press the <ESC> key to enter an escape code! This key allows you to ABORT updating a printer table. To enter an escape code as part of a printer string, you must type \027. 3.1.8 Relating a Secondary File For purposes of report, label, and form letter output, you may relate or link a secondary data base to an identical field in the primary data base if the following conditions are met. (1) The secondary data base must be in the default directory or in the path specified by the DOS PATH command. (2) The secondary data base must be indexed on a field identical in size, type, and field name with a field in the primary data base. Note that the matching field in the primary data base need not be indexed. Whenever a report, label, or form letter is run while a related file and index are set, the developer may access data in any of the fields of the matching related file record by specifying the field names with the following syntax: ALIAS->fieldname where ALIAS is the name of the related file and FIELDNAME is the name of the field to be output from the related file. A secondary file may be related in one of two ways. The first is to select the Z - Zoom/Relate File option on the Main System Menu and enter the name of the file and index to be related. This relation stays in effect until changed provided you save it as part of the configuration. Once a file has been related successfully, the file name display on the last line of the Main System Menu screen should look like the following: FILE: ACCOUNTS/R Any reports. labels, or form letters produced after relating the secondary file may access the fields in the related file also. The second method of relating a file and index is as part of developing the WAMPUM PreFormatted Output file. This is discussed in a subsequent section of the User's Guide. It provides additional flexibility since it permits the developer to relate different secondary files and indexes to different reports, labels, and form letters. WAMPUM Preformatted Output does not rely upon the relation established using the Z option. - 40 - 3.1.9 Storing the New Configuration (WAMPUM.MEM) The configuration of a given application is stored in a configuration file called WAMPUM.MEM. You can change the default configuration by picking the configuration option from the Main System Menu. Select * - CONFIG Update. For each application you build, you may store certain information as a configuration: (1) A Heading for the Main System Menu (2) The Default Drives for the Main Data Base, Related Data Base, and All Other Files (3) The Name of the Main Data Base, Related Data Base, and Associated Indexes (4) The Name of the Printer Configuration File (5) Whether to Disable Certain Choices on the Main System Menu (6) Whether WAMPUM is started with BROWSE mode ON (7) Whether WAMPUM should maintain an Audit Trail (8) Whether Users must confirm data entry by pressing the <ENTER> key in each field (9) The Left and Right Margin settings for Form Letters (10) The Output Print Device or Printer Output File Name if Network mode is enabled (11) Whether to Enable Network File Sharing Once the application is reconfigured, then WAMPUM remembers the new configuration the next time WAMPUM is run whether it is run in Developer or End-User mode. This permits a developer to completely customize a WAMPUM application and then turn it over to end-users without the end-user having to master all of the concepts involved in building an application from the ground up. 3.1.10 Building Reports, Labels, and Form Letters 3.1.10.1 REPORTS 3.1.10.1.1 Overview WAMPUM Reports are designed using the Autumn '87 Clipper REPORT Generator, which Nantucket generously has allowed us to distribute without charge. Before you can create new report forms or revise old ones, you need to make sure the program REPORT.EXE is located in a directory supported by your DOS PATH command. This will assure that WAMPUM can access the report generator whenever you want to design or redesign a report form. - 41 - As indicated previously, WAMPUM requires a minimum of 420K memory to access the report writer from within WAMPUM with DOS 3.1. If you are short on memory, you can run REPORT.EXE from the DOS level by typing REPORT filename where filename is the name of the report you wish to create or revise. Before designing a report, you will always want to print out a listing of the file structure with which you will be working. Pick the S - Select Utilities option and specify T or Y for the List File Structure option. Then type Y when asked whether to print the structure listing. The Clipper Report Generator is quite similar to dBASE III's report writer which is accessed in dBASE with the command CREATE REPORT filename or MODIFY REPORT filename. Thus, anyone who is generally familiar with the dBASE III method of designing report forms will have no problem doing the same with WAMPUM. Please note that WAMPUM 3.1 includes the new Clipper REPORT Generator which accomodates special features added with dBASE III Plus. A report form is a file which contains a template telling WAMPUM which pieces of information you want to extract from a data base. Note that we said "which pieces of information" meaning which fields rather than which records. This is an important distinction since neither WAMPUM reports nor dBASE reports control which records print on a report. That is controlled with record selection using the S - Select Utilities option in WAMPUM. You might more accurately refer to report forms as a formatting mold through which you "pour" information from a data base. All WAMPUM reports must have a DOS-standard file name with no file extension. As is true with dBASE, WAMPUM supplies the file extension of .FRM with all report forms. The R - REPORTS Menu option on the WAMPUM Main System Menu provides three capabilities to the user. First, you can run any existing report form whether created with the Clipper Report Generator or with the dBASE III Plus report writer. Second, you can create new report forms using the Clipper Report Generator. Finally, you can revise existing report forms using the Clipper Report Generator. The reports need not have been created originally with the Clipper Report Generator. How to run reports is explained in the end-user section of this User's Guide. The following two sections address how to create new report forms and revise old ones. 3.1.10.1.2 Creating A New Report Format After printing a listing of the file structure with which you will be working, the next step in creating a new report form is to select the R - Reports Menu option from the WAMPUM Main System Menu. When prompted for the name of the report form to run, type an asterisk (*) and press the <PgDn> key. Then enter - 42 - the name you wish to assign to this new report form. Do not enter a file extension since WAMPUM automatically assigns .FRM as the file extension in keeping with the dBASE naming convention. WAMPUM then will run the Clipper Report Generator assuming you have sufficient memory to support it and assuming WAMPUM can find REPORT.EXE in the DOS PATH. As is true with the dBASE III report writer, the Clipper Report Generator divides a report into three parts: 1. Page Heading & Format Settings 2. Break Level Controls 3. Report Column Contents & Headings The Page Heading & Format Settings screen allows you to specify the title of your report as well as the dimensions of the paper on which the report will be printed or displayed. You also indicate whether the report should be single or double-spaced and whether form feeds should be generated before and after a report is produced. Unlike dBASE III, WAMPUM always generates a form feed at the end of a report whether requested or not. This assures your printer always is at TOP OF FORM for the next job. For the Page Heading, just type in whatever title you want to appear at the top of your report when it prints out. Do NOT center the title since WAMPUM will do this for you automatically. If you want a multi-line heading, just type it the way it should appear at the top of each page of the report. Once you have entered a Page Heading, press the <ENTER> key to move to the Format Settings fields. There are eight options: 1. Enter page width . . . . . . 80 2. Enter left margin . . . . . . 8 3. Enter right margin . . . . . 0 4. Enter no. lines per page . . 58 5. Double spaced report? . . . . N 6. Page eject before printing? . Y 7. Page eject after printing? . N 8. Plain page . . . . . . . . . N Shown beside each of the above entries is the default value which will be used unless you change them. The Plain Page option controls whether a report heading with date prints at the top of each page of your report. For normal printers, the default settings usually are fine except you may wish to narrow the left margin to about 2 just to provide more report space for information. In addition, you may wish to change the page eject before printing option to N. - 43 - For those using a laser printer, you will need to adjust the settings or your reports will run off the bottom of the page since most lasers force a 1/2 inch margin at the top and bottom of a page. With standard 10 pitch, portrait mode reports, the appropriate settings are 80, 2, 0, 56, and N or Y depending upon whether you want the report single or double-spaced. If you are printing sideways (landscape mode) with FONT8 (10 pitch) or with FONT9 (16 pitch), then the settings should be as follows: FONT8: 105, 2, 0, 40, and N or Y FONT9: 160, 2, 0, 40, and N or Y Once you have entered the Page Heading and report settings, press the <PgDn> key to display the second screen of the Clipper report generator. This screen is used principally to break reports into sections based upon a change in the value of some key field in the data base. For beginners, just press <PgDn> to skip this screen. For experts, you should recall that your report will not break properly on the field specified in Group/Subtotal on unless that same field is the primary index in use when the report is run. Similarly, if you specify a subgroup field name, this must be a subfield in the primary index as well. An example may clear the air a little. Suppose you are producing a report of beauty contestants, and you want the report paginated by state and subdivided within the state by the city of residence of each contestant. To produce such a report, you first would need to build a special index (**), give the index a name such as STATCITY, and specify the fields to be indexed as STATE+CITY. Whenever the report is run, that index must be the primary index. Then, in the report form, specify Group/subtotal on: STATE, Summary report only? N, Eject after subtotal? Y, Group/subtotal heading: Contestant state is , Subgroup/subsubtotal on CITY, Subgroup heading: Contestant city is . What happens if you forget to set the primary index to STATCITY? When the report is run, WAMPUM assumes you know what you are doing. So, as the report sifts through your data base, it will do just what you told it. Whenever, the city of the contestant changes, the report will print a subheading of Contestant city is Los Angeles or whatever, and when the state changes, the report will issue a page break and print a new page heading and group heading at the top of the next page saying Contestant state is Utah or whatever. However, since you forgot to put the proper index in effect, the actual records in the data base will not be in STATE and CITY order. Thus, you may get a page with one contestant from California, then a page with one from Utah, then another page with one from California, etc. In short, you probably will get about a 200 page report rather than - 44 - the 5 page report you expected. As noted earlier, if you are a beginning report writer, skip this screen in the report writer until you invest in your own paper company. The meat of the coconut in creating report forms is the Field Contents screen. This is the screen on which you tell the report generator which piece of information you want printed on the actual report. For example, we may want to print the beauty contestant's name, her hometown, state, birthday, and, of course, measurements. Each field of information should be specified on a separate Field Contents screen (unless you are an expert). When you finish specifying one field of information to be output, you simply <PgDn> to get another screen. This process continues until you have specified all of the pieces of information to be printed in the various columns of your report. Note that each screen asks for five pieces of information: 1. CONTENTS 2. # decimal places 0 3. Totals? N 4. HEADER 5. WIDTH For purposes of our example, let's assume the finished report should output something like the following: CONTESTANT'S NAME HOMETOWN STATE BIRTHDAY MEASUREMENTS ----------------- ---------- ----- -------- ------------ Betty Boop Podunck CA 09/27/68 38-22-36 Dolly Partin Nashville TN 09/27/45 48-28-38 CONTENTS is asking for the legal field name of the field to print in the current column of the report. For experts, CONTENTS may also contain any legal dBASE expression. In addition, you can force WAMPUM to create multi-line reports by specifying more than one field name for the contents field. See the special note on the correct syntax for this below. Columns of a report are built from left to right across the screen or page when a report is produced. Since we want the contestant's name in the first column, we would specify FULLNAME as the field to print assuming this was the name assigned to this field in our data base. You can press the DOWN CURSOR or <ENTER> key to move down to the # decimal places field; however, the DOWN CURSOR is safer since a little Clipper bug sometimes assumes you're finished building your report when you press <ENTER>. Unless you have specified a numeric expression for the CONTENTS, both the # decimal places field and the Totals? field should be left alone. If you are outputting numeric data, then the # decimal places field allows you to specify how many decimal positions should be printed for this column of the report. Enter a number and press the DOWN CURSOR. Totals? allows you to specify whether you want the numeric expression totaled (and subtotaled) at breaks in the report and at the end of the - 45 - report. Note again that you cannot TOTAL anything except a numeric expression. If you just want a COUNT of records, this is covered below separately. Then, DOWN CURSOR to the HEADER field. HEADER is asking for the column heading to display for this column of the report. This is free-form text of your choosing. It should convey to the reader of the report what the contents of this column of the report actually are. The only precaution here is that the header typically should not be much wider in length than the maximum field width being displayed in this column. Otherwise, you are just wasting space across the report since the WIDTH must be the wider of the field maximum width and the header width. In the example above, type CONTESTANT'S NAME on the first header line, then press the DOWN CURSOR and type ---------------- on the next line to simulate an underscore. Use the DOWN CURSOR to move down to the WIDTH field. WIDTH is asking for the column width of this column of the report. As noted above, this width should be the greater of the field maximum width or the longest line of the column headers. Note that the Clipper Report Generator loves the number 10. This is the default, and occasionally when you edit a previous report, the report generator sometimes forgets the width you previously specified. You may have to reenter it. Once you have entered the width desired, press <PgDn> and a second Field Contents Screen will appear. Fill this one in for the next column of your report, then <PgDn> again. Continue this process until you have completed all of the fields which you want output in the report. Then <PgDn> to another blank Field Contents Screen. Note that you MUST ALWAYS be on a blank Field Contents screen before electing to SAVE your report template. If you violate this rule, you probably will lose some of the columns of your report. Press the <ESC> key to tell the report writer you are finished. You will be asked whether you are finished. Typing a Y saves the report form to disk. Typing an N returns you to the top of the current Field Contents Screen. Pressing <ESC> aborts the report creation process and does NOT save the report. What happens if you want to change something before you have first saved the report? Simply press <PgUp> to move back through the screens you have already entered. Then <PgDn> to return to a blank Field Contents Screen before SAVING the report. You probably will have to use the <ENTER> key to move through the last completed Field Contents Screen to get to a blank screen. Suppose you want to count the number of records output in the report. This is perhaps the weakest link in both the dBASE report writer and the Clipper clone. The easiest method for doing this is to include a final Field Contents Screen with the following specifications. For the CONTENTS, type the number 1. For DECIMALS, leave it at 0. For TOTALS, type Y. For the HEADER, type TOTAL and a second row of -----. For width, type 5. This will tell WAMPUM to count the records as the report is - 46 - produced and print a total at the bottom. It will also uglify your report by producing a column of 1's along the right margin of your report. Suppose you want to do some date calculations. In the above example, suppose we want to compute the beauty contestant's age. For the CONTENTS field, specify (DATE()-BIRTHDAY)/365. Leave the decimals at 0, and totals as N. For HEADER, insert AGE on the first line and --- on the second. For WIDTH, type 3. This tells WAMPUM to perform the following calculation each time a record qualifies for the report and output the answer in this column. Subtract the contestant's birthdate from today's date. This yields a number. Divide this number by 365 to get the AGE in years of the contestant. Note the parentheses around the subtraction. In algebra, multiplication and division take precedence over addition and subtraction. This means that WAMPUM would ordinarily attempt to perform the division before the subtraction. Since you cannot divide a DATE field by a number, this would send WAMPUM into the OZONE when the report was run. The parentheses tells WAMPUM to carry out the calculations in parentheses first before performing the division. Since dBASE and WAMPUM can add and subtract dates, this will yield a numeric value which then can be divided by 365. Suppose you want to output the contents of a MEMO field in a report. A minor "bug" in the Clipper compiler causes WAMPUM reports with a MEMO field to format strangely. This now has been fixed through the addition of a new function: MEMOTRAN(). To output a MEMO field, enter the following expression for the field contents: MEMOTRAN(fieldname) where fieldname is the actual name of the MEMO field in your data base. You may specify a column width of any length desired and WAMPUM will format the output accordingly. Again, special thanks to Nantucket for providing this "fix" at no expense to anyone. Suppose you want a multi-line report with a name and address in a single column followed by several other pieces of data in separate columns. For the contents field, you may specify more than one field for output in the column so long as all the fields evaluate to character strings. To force multiple lines within a column, you simply reduce the column width to account for the amount of data which should display on each line plus one space. Then adjust your various lines of data to match the column width. A simple example should help. Assume you have a data base with a 15 character FIRSTNAME field, 15 character LASTNAME field, 30 character ADDRESS field, 15 character CITY field, and 2 character STATE field. When the report is produced, we want all this information displayed in a single, multi-line column of the report. To get the FIRSTNAME and LASTNAME fields to display on the same line would require 30 characters plus a space between the two fields and one space at the end of the LASTNAME to break the line. Thus, the column width should be set to 32. The correct CONTENTS expression would be as follows: SUBSTR(TRIM(FIRSTNAME)+SPACE(1)+LASTNAME+SPACE(31),1,32)+ ADDRESS+SPACE(2)+TRIM(CITY)+", "+STATE - 47 - WAMPUM reports also support the immediate IF function implemented in dBASE III Plus. The syntax of the function is as follows: IIF(Logical Expression,On True,On False). This may be included to branch to one of two values in a report depending the value of the logical expression. For example, suppose you wanted to display "HITCHED" if a MARRIED field was True but "AVAILABLE" if the field was False. The correct syntax in your CONTENTS field of the report would be IIF(MARRIED,"HITCHED","AVAILABLE"). Note that the OnTrue and OnFalse values may be character strings, dates, numeric values, or logical expressions so long as both are of the same data type. Any good reference work on dBASE III Plus can provide more examples of the immediate IF function. The final thing to be careful of in creating reports is to make sure the total field widths specified for your report do not exceed the PAGE WIDTH specified when you set up the report. A little math in advance will solve this problem. Remember that WAMPUM always leaves a single space between columns of the report. This is in addition to the field widths you specify! 3.1.10.1.3 Modifying Existing Report Formats To modify an existing report, select the R - Report Menu option from the Main System Menu. Look at the listing of reports which displays and write down the name of the one to be modified. Then type an asterisk (*) as if you were creating a new report. Press <PgDn>. When WAMPUM prompts for the name of your new report, enter the OLD name and press <ENTER>. The discussion above with respect to creating a new report applies as well to modifying an existing one. As noted, be careful to check the defaults and make certain the Clipper Report Generator did not reimpose its defaults rather than the values you specified. You then can SAVE or ABORT saving the revised report just as was done in creating a new one. Before SAVING a report, make certain that you have moved to the end of your existing report template and that a BLANK CONTENTS field is displayed on the screen! 3.1.10.1.4 Outputting MEMO fields in Reports MEMO fields may be formatted as columns in a report just like a character string except for the syntax of the CONTENTS expression. With character fields, you typically specify the actual name of the field to be output. With a MEMO field, use the following syntax where COMMENTS is the actual field name given to the MEMO field you wish to output in the report: MEMOTRAN(COMMENTS) MEMOTRAN is a Clipper function which fixes a quirk in the Clipper report writing software. Using the above syntax will permit a MEMO field to be produced in a report column of - 48 - virtually any width desired. Simply specify a field width of your choice and the MEMOTRAN function will assure that the text in the MEMO field is word-wrapped to fit in the specified width. 3.1.10.2 LABELS 3.1.10.2.1 Overview WAMPUM Label Templates are designed using the Clipper LABEL Generator, which Nantucket generously has allowed us to distribute without charge. WAMPUM requires 420K to access the label generator program from the Main System Menu. If you are short on memory, you may run the label program from the DOS prompt using the following syntax: LABEL filename where filename is the name of the label template to be created or revised. Before you can create new label templates or revise old ones, you need to make sure the program LABEL.EXE is located in a directory supported by your DOS PATH command. This will assure that WAMPUM can access the label generator whenever you want to design or redesign a label form. You should also be aware that beginning with DOS 3.0, a DOS program named LABEL.COM is provided to rename volume labels. Make certain that your DOS PATH checks the subdirectory containing Clipper's LABEL.EXE program before checking the DOS subdirectory containing LABEL.COM. Otherwise, WAMPUM will execute the wrong program when you attempt to create or revise label forms. Another approach is to rename LABEL.COM to some other file name such as NEWLABEL.COM. This will avoid conflict. Before designing a label, you will always want to print out a listing of the file structure with which you will be working. Pick the S - Select Utilities option and specify T or Y for the List File Structure option. Then type Y when asked whether to print the structure listing. The Clipper Label Generator is quite similar to the dBASE III label writer which is accessed in dBASE with the command CREATE LABEL filename or MODIFY LABEL filename. Thus, anyone who is generally familiar with the dBASE III method of designing label forms will have no problem doing the same with WAMPUM. A label form is a file which contains instructions telling WAMPUM which pieces of information you want to extract from a data base and place on labels. Note that we said "which pieces of information" meaning which fields rather than which records. This is an important distinction since neither WAMPUM labels nor dBASE labels control which records print on a label. That is controlled with record selection using the S - Select Utilities in WAMPUM. You might more accurately refer to label forms as a formatting template through which you "pour" your data. - 49 - All WAMPUM labels must have a DOS-standard file name with no file extension. As is true with dBASE, WAMPUM supplies the file extension of .LBL with all label forms. The L - LABELS for Mail option on the WAMPUM Main System Menu provides three capabilities to the user. First, you can run any existing label form whether created with the Clipper Label Generator or with the dBASE III or dBASE III Plus label maker. Second, you can create new label forms using the Clipper Label Generator. Finally, you can revise existing label forms using the Clipper Label Generator. The labels need not have been created originally with the Clipper Label Generator. How to run labels is explained in the end-user section of this User's Guide. The following two sections address how to create new label forms and revise old ones. 3.1.10.2.2 Creating A New Label Format After printing a listing of the file structure with which you will be working, the next step in creating a new label form is to select the L - Labels for Mail option from the WAMPUM Main System Menu. When prompted for the name of the label form to run, type an asterisk (*) and press the <PgDn> key. Then enter the name you wish to assign to this new label form. Do not enter a file extension since WAMPUM automatically assigns .LBL as the file extension in keeping with the dBASE naming convention. WAMPUM then will run the Clipper Label Generator assuming you have sufficient memory to support it and assuming WAMPUM can find LABEL.EXE in the DOS PATH before finding DOS's LABEL.COM program. As is true with the dBASE III label writer, the Clipper Label Generator divides a label form into two parts: 1. Label Settings 2. Label Contents There are six items of information which can be set to specify how the labels should be produced. These include the following with their default settings: 1. Width of Label 35 2. Height of Label 5 3. Left Margin 0 4. Lines Between Labels 1 5. Spaces Between Labels 0 6. No. of Labels Across 1 Width of Label refers to the maximum width of any text entry on any label produced. Height of Label means the maximum number of lines per label. Left Margin is the starting column position for the left-most label. Lines Between Labels specifies the number of blank lines between each completed label. Spaces Between Labels is the number of blank columns horizontally - 50 - between labels when two or more are produced across the page or screen. Number of Labels Across allows you to specify how many columns of labels will be printed across the page (up to 5). The main consideration to keep in mind in producing labels is the following. There is no pagination control for labels. All label forms assume an unending supply of continuous-form label stock in your printer. If you are using a laser printer, then printer codes will have to be used to set top of form and page length to match the label format desired with one exception. WAMPUM knows the format for 33-UP LABELS (11 labels per page with 3 across) if you use the following settings for the label form and specify FONT7 with the HPLASERA or HPLASERB printer table: 1. Width of Label 24 2. Height of Label 4 3. Left Margin 0 4. Lines Between Labels 2 5. Spaces Between Labels 4 6. No. of Labels Across 3 Once you have entered the label settings desired, press <PgDn> to move to the Label Contents Screen. In this screen, you enter field names to be produced on the labels much as was done on the Field Contents Screen with Report Forms. Then press <ESC> when you have completed filling out the field expressions which should appear on each line of the label. You will be prompted to answer whether to save the new label format. A sample of field expressions appears next for a typical mailing label. All of the names in BOLD are assumed to be the actual field names: 1 TRIM(FIRSTNAME) + " " + TRIM(LASTNAME) 2 ADDRESS1 3 ADDRESS2 4 TRIM(CITY) + ", " + TRIM(STATE) + " " + ZIPCODE 3.1.10.2.3 Modifying An Existing Label Format To modify an existing label format, select the L - Labels for Mail option from the Main System Menu. Look at the listing of labels which displays and write down the name of the one to be modified. Then type an asterisk (*) as if you were creating a new label form. Press <PgDn>. When WAMPUM prompts for the name of your new label, enter the OLD name and press <ENTER>. The discussion above with respect to creating a new label applies as well to modifying an existing one. As noted, be careful to check the defaults and make certain the Clipper Label Generator did not reimpose its defaults rather than the values you specified. You then can SAVE or ABORT saving the revised label form just as was done in creating a new one. - 51 - 3.1.10.3 FORM LETTERS 3.1.10.3.1 Overview One of the most critical limitations of dBASE III has been its lack of a convenient "mail merge" interface which would allow selected data to be extracted from a data base and inserted into form letters. WAMPUM now provides this missing link through its built-in Form Letter generator. Actually, a WAMPUM form letter is nothing more than a standard dBASE III data base with a single field designated as LINE1. In executing a form letter merge through either the T - Form Letter Menu or via W - Wampum Preformatted Output, WAMPUM simply extracts data from your data base and merges it with the text contained in the form letter data base file you specify. WAMPUM automatically handles word wrapping as part of the merge process. In addition, the Form Letter Generator includes powerful programming functions which allow you to test the contents of fields in a data base and branch to various paragraphs of the form letter depending upon the contents of the data base. The current version of WAMPUM assumes that you will be outputting your form letters on 8-1/2 x 11 paper using 10 pitch type. You may adjust the left and right margin settings in the WAMPUM Configuration Screen if necessary. Based upon end-user's suggestions, a number of enhancements have been added to the form letter functions in WAMPUM 3.1. These include the ability to open and manipulate up to 5 related data bases within any form letter file. You also may now use an index to generate a form letter for any selected record in your active data base. This avoids having to make a full pass through the main data base to generate only a few form letters. The following sections describe how to create an empty form letter as well as how to construct the form letter data base once the file has been created. The end-user section of this Guide describes the process of merging data into a form letter file. 3.1.10.3.2 Creating a New Form Letter File To create a new form letter, select T - Form Letter Menu from the Main System Menu. When prompted for the name of the form letter to run, type an asterisk (*) and press <PgDn>. You then will be prompted to name the new form letter. This name must start with T- and then up to a 6 character name. WAMPUM will add the .DBF file extension and build the form letter file. 3.1.10.3.3 Building Data in Form Letter File To actually build the form letter, use F - File Select to select the form letter file with which you want to work, just as you would select any other data base file to use. - 52 - Before actually entering data for the form letter, some explanation of how form letters are constructed and how they are output will assist in your design. When WAMPUM generates form letters, it reads the form letter file to get the text for the form letter. All leading and trailing spaces in each record are stripped off when WAMPUM builds the text to print. WAMPUM then reads the next record in the form letter file and appends it with a single leading space to what was in the previous record. For example, each field in a form letter record may contain up to 136 characters. Suppose the the following two records were in the file: Hello there, Cutie! When this form letter was printed, the text would read: Hello there, Cutie! Note that there would be no indentation from the left margin, and all other spaces would be trimmed except the one space added between the two records. How do you get spaces when you really want them? This is done by inserting CHR(255) on the left margin of a record. Then it can be followed by as many spaces as desired. To insert this character, hold down the ALT key and type 255 with the numeric keypad. WAMPUM Form Letters also may contain markers (field data expressions) which tell WAMPUM to extract or evaluate information in the primary data base when the form letter is merged. The main rule to remember insofar as field data expressions are concerned is that you may have only one such expression in each record of a form letter file. A FIELD DATA EXPRESSION always begins and ends with //. In its simplest form, an expression such as //LASTNAME// would tell WAMPUM to extract the contents of the LASTNAME field in the current record and insert it into the form letter at this place. The beginning and ending //'s must be part of the same record. With some Field Data Expressions, you may block off a section of text in the form letter which will be affected by the evaluation of the expression itself. For instance, if a particular field is blank in the data base, WAMPUM form letters may contain a special code telling WAMPUM to omit all of the text which has been blocked off. TEXT MARKERS consist of @@ at the beginning and ending of the affected text. Note that these markers may not extend beyond a single record. Thus, you cannot have one pair of @'s in record 5 and the other pair in record 6. - 53 - An example of the syntax would be the following. Suppose you want to thank people for contributing to your reelection campaign. In your data base is a field CONTRIBDT which will be empty if no contribution has been received. The record entry in the form letter might say: @@Thanks for being such a great supporter!//*CONTRIBDT//@@ This entry means if CONTRIBDT is not blank, then print the text: Thanks for being such a great supporter! Otherwise, leave this sentence out of the form letter entirely. The following section describes all FIELD DATA EXPRESSIONS implemented as of version 3.1 of WAMPUM. Another difference in WAMPUM Form Letters and standard text is that WAMPUM needs to know when you really do want to end a paragraph. This is referred to as a hard carriage return with many word processing packages. WAMPUM interprets a blank record in the form letter file or a record beginning with a tilde (~) as a hard carriage return. Note that if you want a hard return in a form letter and a blank line between paragraphs, you will need to insert two blank records in the form letter file or two records beginning with a tilde. All text following a tilde is ignored if the tilde is the first character on the line. Finally, remember that WAMPUM form letters are built on the fly when you actually run the form letter program. Make certain that you end all form letter files with at least one blank record and preferably two. This will assure that the form letter buffer is purged before the next form letter is produced. 3.1.10.3.4 WAMPUM Field Data Expressions What follows is a listing of the syntax for various FIELD DATA EXPRESSIONS together with an example of each expression. The best way to get a feel for using WAMPUM Form Letters is to build a few. It provides more power and flexibility in this area than any commercial product on the market. Like any powerful programming tool, however, it takes a little getting used to. //LASTNAME// Allows imbedding a character, numeric, or date field within a form letter record. It would output Jones if Jones were in the LASTNAME field. Note: if a date field, it outputs the date in the format May 21, 1986 if entry is 05/21/86. @@Thanks //LASTNAME//.@@ Allows imbedding a CHARACTER FIELD with a string of text which will print only if the field is not blank. It would output Thanks Jones. if Jones were in the LASTNAME field. - 54 - @@Filed.//*FILINGDT//@@ Tests whether a particular character, numeric, or date field is not blank or whether a logical field is True. In either case, if True the output would be Filed. Otherwise, nothing would be printed. @@Not filed.//#FILINGDT//@@ Just the opposite of the above. If the character, numeric, or date field is empty or if the logical field is False, the expresion is printed. Otherwise, nothing would be printed. @@A new baby!//?PREGNANT//@@ Similar to above. Used only with a logical field. If logical field is True, the expression is printed. @@So you're 30.//!AGE=30//@@ Allows any dBASE III expression as the test for whether the text should be printed. If the test is True, the text is printed. Make certain that both sides of the expression are of the same data type. This example would print So you're 30! if the AGE numeric field = 30. // AGE=30// This is the syntax for a GOTO using the WAMPUM form letter generator. Note the SPACE at the beginning of the expression which means, IF the expression is True, SKIP to the next record beginning with a SPACE character. If you want to skip past a required carriage return record, make certain that the record begins with a tilde and not with a SPACE since blank records are assumed to be those containing all spaces. //+SAMPLE.DOC// With lengthy pieces of text with no embedded data, it is often easier to type them into a plain ASCII document using a text editor. You then can merge them into a WAMPUM form letter with the syntax shown which says read in the SAMPLE.DOC text file at this point in the form letter. Note that this command should appear in a record by itself with no other text. //=DTOC(DATE())// There may be times when you just want to reformat some data directly out of the data base. The = operand allows this to be done with any dBASE expression so long as it evaluates to a STRING EXPRESSION when it is processed. //<#,filename,indexname// Using the < command allows you to open up to 5 related data bases from within a form letter file. Replace the pound sign (#) with a number from 5 through 9. Note that 5 corresponds to the number of the related data base opened with the Zoom/Relate File option. It need not be reopened. Paths may be included in identifying both the filename and the indexname. - 55 - //>#,string expression// Using the > command permits you to do an indexed SEEK by key value to any record in the file identified by the number replacing #. This numbered file and a corresponding index must already have been opened using the < command. The string expression may be the contents of a field in the primary data base or any dBASE string expression. If the name of a field in the primary data base is used, be sure to precede it with the ALIAS for the file using the following syntax: ALIAS->fieldname where ALIAS is the actual file name of the primary data base and fieldname is the legal field name of a field in the primary file. Once the SEEK has been accomplished, any data in the secondary data base may be extracted using the = field data expression outlined above and the ALIAS->fieldname syntax where ALIAS is the name of the secondary data base file and fieldname is the name of a field in that file. //FF// The FF command allows the user to generate a form feed or page eject from within a form letter file. 3.1.11 Building Function Key Macros (KEYS.DBF) As an aid in data entry intensive applications, WAMPUM provides the capability to define up to 39 keyboard macros which may be invoked by the end-user simply by pressing a function key. As is true with WAMPUM applications generally, these keyboard macros are application specific. This simply means that a set of keyboard macros may be defined for each application in each new directory created on the hard disk. The name of the file which stores the macros is KEYS.DBF which is a standard dBASE III data base file. It is created automatically whenever WAMPUM is first run in a new subdirectory. To build the table of macro definitions, follow the steps below. First, select the KEYS.DBF file as the file with which you want to work by picking the F - File Select option on the Main Menu. Enter the file name KEYS when prompted to do so. When the Main Menu reappears, the bottom line of the screen should say: FILE: KEYS Next, you will want to figure out what keystrokes you want to store under which function keys. The following function keys are available for use: F2 - F10 Shift F1 - Shift F10 Ctrl F1 - Ctrl F10 Alt F1 - Alt F10 - 56 - You will note that this is all function key combinations except for F1 which is reserved by WAMPUM as the HELP key. Record numbers in the KEYS file match the function keys by key number. See the table below: Function Keys Record Numbers -------------------- -------------- F2 - F10 Rec # 2 - 10 Shift F1 - Shift F10 Rec # 11 - 20 Ctrl F1 - Ctrl F10 Rec # 21 - 30 Alt F1 - Alt F10 Rec # 31 - 40 Thus, whatever keystrokes are entered in record 5 of the KEYS file will automatically be assigned to function key F5. Those in record 40 will be assigned to function key ALT-F10. Any record in the KEYS.DBF file which is blank will be ignored. There are two cardinal rules to remember in entering data in the records of the KEYS file. (1) Record 1 of the KEYS file is always ignored since it corresponds to the HELP function key, F1. (2) Every entry in the KEYS file must equate to a CHARACTER STRING when evaluated by WAMPUM. The first rule is only logical. Since F1 is reserved for HELP, the corresponding record in the KEYS file is ignored. Whatever is entered in this record won't matter because it is ignored. Note that you will have to ADD a first record which automatically will be record 1. Simply press <ENTER> to save it and create record 2 which can be used. The second rule is critical because if it is violated you will get run-time errors the next time WAMPUM is started. If this happens, simply type I to ignore each error (which means that function key will not be set), then edit the records causing the problems following the steps outlined above. Translated into dBASE III lingo, each record in the KEYS file must be a character string. If it is simply character data, you meet this requirement by enclosing the data in double or single quotes. If you have single quotes in the string, then enclose the string in double quotes and vice versa. You can also use dBASE III functions and special WAMPUM functions to create macros so long as the expression evaluates to a string. Here are a few examples to get you started: DTOC(DATE()) would store today's date as a macro in the following format: 10/10/86. FULLDATE(DATE()) would store today's date as a macro in the following format: October 10, 1986. DTOC(DATE()+30) would store today's date + 30 days. - 57 - CDOW(DATE()) would store the day of the week in a macro in the following format: Tuesday. STR(YEAR(DATE()),4) would store the year as a string in the following format: 1986. WEEKDAY(DATE()+30) would store the date 30 days from today rolled over to Monday if it hits on weekend in format: 10/10/86. Again, the important thing to remember is that character text must be enclosed in quotes, and data other than character data must be converted into a string using one of the dBASE III or WAMPUM conversion functions. Finally, these keyboard macros will not take effect until the next time WAMPUM is run from DOS. They will be loaded on each subsequent running of the program unless changed. Developers should be careful not to store a file named KEYS.DBF in the DOS PATH unless you intend to invoke the macros contained therein whenever an application starts and a file named KEYS.DBF cannot be found in the default directory. 3.1.12 Building Edit Checks (EDIT.DBF) As an aid in data entry accuracy, WAMPUM provides the capacity to design custom edit checks for each WAMPUM application. As was true with keyboard macros, a set of edit checks may be defined for each application in each new directory created on the hard disk. The name of the file which stores the edit checks is EDIT.DBF which is a standard dBASE III data base file. It is created automatically whenever WAMPUM is first run in a new subdirectory. To build the table of edit checks, follow the steps below. First, select the EDIT.DBF file as the file with which you want to work by picking the F - File Select option on the Main Menu. Enter the file name EDIT when prompted to do so. When the Main Menu reappears, the bottom line of the screen should say: FILE: EDIT Next, you will want to figure out what edit checks you want to develop for the particular application. For some applications, you may want to assure that a data entry field is never left blank. For others, you may want to assure that a duplicate key is never entered. Finally, you may want to assure that an entry is contained in a table of valid entries. None of these checks are possible in dBASE III without substantial custom programming. WAMPUM provides this capability with a few minutes work. - 58 - The EDIT file structure consists of two fields: EDITTEST and ERRMSG. The theory behind WAMPUM edit checks is a simple one. Once you "turn on" the edit checks for use against a particular file, WAMPUM automatically tests newly added records as well as updated existing records to make certain that they do NOT violate any of the error conditions (EDITTESTs) you have specified in the EDIT file. The checks are only run when new records are added to a data base or existing records are changed. For each error condition identified, WAMPUM will display an error message (ERRMSG) and then permit the end-user to fix the problems. The end-user cannot SAVE the record with errors without correcting them. The end-user may <ESC>ape from a data entry screen without invoking WAMPUM's edit checking. Since developers typically work with several files in creating a new application, there are some instances in which you would not want the EDIT CHECKS to occur. Most importantly, when the primary data base is not being used, you would not want to invoke a series of edit checks designed to check primary data base information. This is handled in a simple way. WAMPUM always reads the EDITTEST field entry in the first record of the EDIT.DBF to ascertain the name of the file to be checked. If this entry does not match IN UPPER CASE the name of the current file in use, the edit checks are turned off. Stated somewhat differently, the EDITTEST field of Record 1 of EDIT.DBF is reserved to hold the UPPER CASE name of the data base to be edit checked. Thus, in the case of our example, the entry in Record 1 of EDIT.DBF should say ACCOUNTS. If you forget to enter the name of the data base file to be checked in record 1, then obviously the edit checks specified will never be invoked! There also may be occasions where you want to specify the actual fields to be displayed with BROWSE MODE ON rather than accepting WAMPUM's default which is the first few fields in the actual data base structure. If you want to specify your own fields, insert the following in the ERRMSG field of Record 1. The first character must be an asterisk (*). It is followed by the field numbers (from your file structure listing) of the fields you want displayed. All numbers must be three characters wide and should be padded to the left with spaces. Three digit numbers should be preceded by a single space. For example, if you want the fields LASTNAME, ACCTNO, and SEX display in BROWSE mode and these are fields 3, 17, and 252 in your data base, the correct syntax would be: * 3 17 252. There are three things to keep in mind in developing your edit checks. First, edit checks must be dBASE III or WAMPUM expressions which can be evaluated as True or False. Second, if the expression in EDITTEST is true, the error message in ERRMSG is triggered. In other words, you are building expressions which identify when an error condition occurs rather than the other way around. Third, and most importantly, if you wish to evaluate data entered in a particular field, you do NOT use the fieldname to test for an error. Instead you use the field's sequential - 59 - number in the data base in conjunction with an array name FLDDATA[]. The next paragraph will clear up any confusion you are momentarily experiencing. Since you need to know a field's position in the file structure in order to develop edit checks, your first step should be to print out the file structure of the file which will be checked. Pick the S - Select Utilities option after making certain that the correct file is in use. Change the List File Structure option to T or Y, then answer Y when prompted for whether the structure should be printed. This will give you the list of fields in the data base. Note that the left column shows the field's NUMBER in the structure. Let us assume that the LASTNAME field is field number 1. An appropriate edit check to assure that the LASTNAME field was not left blank would read as follows: EMPTY(FLDDATA[1]) or in standard dBASE III parlance, you could say FLDDATA[1]=SPACE(20) assuming the field's width was 20 characters. One of the above entries should be entered as the EDITTEST entry in the EDIT file. The ERRMSG field entry might say something like this: The LASTNAME field cannot be left BLANK. Whenever the EDITTEST record evaluates to TRUE, meaning FLDDATA[1] is blank, then the ERRMSG would be displayed. The important thing to remember is to use FLDDATA[1] and not LASTNAME in identifying the field to be checked! Note that you also can check one field against another in the same data entry screen. For example, assume there were two fields in the data base as follows: 1 TRANSCODE Character 8 2 TRANSDATE Date 8 Let's also assume that the format of the TRANSCODE entries is of the form: 86-12345 where 86 identifies the year of the trans- action. One edit check you probably would want to perform in a situation such as this is to make sure the first two digits of the TRANSCODE matched the year in the TRANSDATE field. Here is one possible way to handle that: SUBSTR(FLDDATA[1],1,2)<>SUBSTR(DTOC(FLDDATA[2]),7,2) Note in the example that the relationship must be coded so that when it is TRUE, the error message displays. Thus, we want to code it in such a way that when the first two characters of the TRANSCODE do not match the year in the TRANSDATE, the expression is True and hence the error message is given. Note also that the expressions on both sides of the relational operator must be of the same type. In this case, both are character strings. Finally, it should be noted that these EDIT CHECKS will not take effect until the next time WAMPUM is run with the appropriate file in use. They will be loaded on each subsequent running of the program unless changed. Developers should be careful not to store a file named EDIT.DBF in the DOS PATH unless you intend to invoke the edit checks contained therein whenever an application is run and a file named EDIT.DBF cannot be found in the default directory. - 60 - Beginning with version 2.7 of WAMPUM, several enhancements were added to the EDIT checking module. WAMPUM now supports both calculated fields through the EDIT process as well as "table lookup" to make certain that a field value appears in a given table of values. Creating Calculated Fields To automatically calculate the value for a field, that field must be one of the fields in the active data base. Typically, you would NOT want it to display on a data entry menu since its value will be changed automatically regardless of what the user enters. This calculation capacity may be used to compute both dates and numeric values and where necessary can also compute values for character and logical fields. To automatically calculate the value for a field, follow these steps: (1) In the EDITTEST field, the first character must be the equals sign (=). This is followed by whatever selection criteria will be used to determine when the calculation IS performed. If you want it done whenever a record is added or changed, then the EDITTEST field should look like the following: =.T. WAMPUM keeps track of what mode it is in by setting a variable HELPCODE to the number corresponding to the option picked from the Main System Menu, e.g. A - Add is 1, E - Edit is 2, etc. You may find it helpful to be able to perform calculated field transactions only when the user is in Edit mode or Add mode. If you only wanted a field calculated when a new record was added, use the following syntax in the EDITTEST field: =HELPCODE=1 (2) In the ERRMSG field, two codes must be inserted and they are separated by a comma. The first is the field number corresponding to the field to be calculated. Then insert a comma. Then enter any legal dBASE expression to handle the calculation desired. A simple example may help. Assume that the data base contains a FILINGDT field as #1, a DAYSPEND field as #14, and a CLOSEDT field as #20. Until a closing date entry has been made, we want the computer to recompute the days pending from the filing date whenever a new record is added or changed. The field entries should look like the following: EDITTEST: =EMPTY(FLDDATA[20]) ERRMSG: 14,DATE()-FLDDATA[1] - 61 - Using "Table-Lookup" for Editing "Table lookup" for Editing means the ability of a data base system to refer to a table of values in order to determine whether a value entered by a user is acceptable. Within WAMPUM, table-lookup is implemented using standard dBASE data bases for the tables. These data bases may be checked either sequentially or through a Clipper-index file (.NTX) as the developer desires. To perform "table lookup" as part of the edit checking process, the following rules must be met: (1) In the EDITTEST field, the first character must be a question mark (?) if a non-indexed dBASE file will be used as the table. Or two question marks (??) must be used if a dBASE file table will be checked using a Clipper index as the key. The question mark or marks are followed by whatever selection criteria the developer wants to specify to tell WAMPUM when the table lookup SHOULD be performed. See the examples above. (2) In the ERRMSG field, three values must be inserted with a comma between the values. (a) The first code is the number of the field to be checked against the table. Then type a comma. (b) The second code is the dBASE file name of the table to be checked (without the .DBF extension). Then type a comma. (c) The third code is one of two values. With a non- indexed table lookup (?), the third code is the name of the field in the table lookup file to be compared. With an indexed table lookup (??), the third code is the name of the Clipper index file (without .NTX extension) to use for the lookup. An example may help remove some of the mystery. Assume your main data base has a field #8 for the user to enter the abbreviation of the STATE where the customer lives. You want to make sure this entry is, in fact, a state in the United States. Using WAMPUM, you build another data base with a file name of STATES and an index called ABBREV which holds the two character abbre- viation for each state in the United States. Your entries would look like the following in the EDIT record: EDITTEST: ??.T. ERRMSG: 8,STATES,ABBREV Using "Table-Lookup" for Calculated Fields Just as a table could be checked to verify data in your data bases, WAMPUM also permits table-lookup to actually calculate the contents of fields in your primary data base. The table may be - 62 - accessed either sequentially or through a Clipper-index file (.NTX) as the developer desires. To calculate a table follow these simple steps in adding an entry to the EDIT file: (1) In the EDITTEST field, the first character must be an exclamation point (!) if a non-indexed dBASE file will be used as the table. Or two exclamation points (!!) must be used if a dBASE file table will be referenced using a Clipper index as the key. The exclamation point(s) are followed by whatever selection criteria the developer wants to specify to tell WAMPUM when the table lookup calculation SHOULD be performed. (2) In the ERRMSG field, five values must be inserted with a comma between the values. (a) The first code is the number of the field in the primary data base to be used to find a match in the table. Then type a comma. (b) The second code is the dBASE file name of the table to be checked (without the .DBF extension). Then type a comma. (c) The third code is one of two values. With a non- indexed table lookup (!), the third code is the name of the field in the table lookup file to be compared. With an indexed table lookup (!!), the third code is the name of the Clipper index file (without .NTX extension) to use for the lookup. Then type a comma. (d) The fourth code is the number of the field in the primary data base to be calculated from the table. Then type a comma. (e) The fifth code is any legal dBASE expression which specifies the value to be calculated for the field referenced in (2)(d) above. This expression would include references to one or more fields in the table typically. By way of example, let us assume that a company maintains an ORDERS file with numerous pieces of information being captured about new orders. Among these are the part number (field #1) and the part cost (field #2). There also is a table of PARTS which contains the cost of each part (PARTCOST) in the company's inventory. The developer wants to look up the cost of the part specified in the ORDERS file and insert it automatically into the part cost field in the ORDERS file. The syntax to do this using a PARTS file indexed on part number would look like this: EDITTEST: !!.T. ERRMSG: 1,PARTS,PARTNO,2,PARTCOST - 63 - 3.1.13 Building Data Entry Menus (MENUS.DBF) Up to 9 customized data entry menus may be built for any given application. These typically correspond to different stages in the data entry process for a given data base. In addition to these 9 customized data entry menus, WAMPUM also provides a standard data entry screen which includes access to every field in the current data base. These data entry menus are numbered 0 to 9 with 0 being the default standard menu with access to all fields. In addition to specifying up to 9 custom menus, the developer may also restrict users without the developer password to a given range of menu numbers. Thus, some care must be exercised to group the restricted and non-restricted menus into contiguous numbers. A range of 1 to 5 is permissible, but you cannot allow access to menu 0 as well as menus numbered 2 to 6. Information pertaining to the custom menus is stored in a standard dBASE file named MENUS which is created in the current default directory whenever WAMPUM is first invoked. Each record in the MENUS file corresponds to a custom menu with the same number. Thus, record 1 contains information about menu 1, and so on. To build one or more custom menus, first start up WAMPUM in Developer Mode by specifying the developer password after the word WAMPUM. Make certain that the File in Use at the bottom of the screen is the one for which you want to build the custom menus. If so, choose S - Select Utilities and change the List File Structure field entry to T. Then <PgDn> and print the file structure for reference. When the Main System Menu reappears, pick F - File Select and enter the file name of MENUS. Press <ENTER> and WAMPUM will open the MENUS file. When the Main System Menu reappears, make sure the bottom line of the screen shows the file name MENUS. To ADD a new custom menu, pick A - Add Records from the Main System Menu. A blank record will appear with two fields: MENUNAME and FLDLIST. As the name suggests, MENUNAME is whatever name you want to assign to this custom menu, e.g. CASE OPENING MENU. Enter the title desired and press <ENTER> to move to the FLDLIST field. In FLDLIST, you specify the field numbers corresponding to the fields you want displayed on the data entry screen. The sequence used to specify the numbers does not matter since the fields always are ordered according to their numeric position in the data base structure. The format for these field numbers is CRITICAL! Rule 1: Each field number must be AT LEAST 3 characters in length with spaces to the left of the number to "pad" it to 3 characters. For example, field 1 would require that you type two spaces and then the number 1. 27 would require one leading space and then the number 27. - 64 - Rule 2: Each field number must be preceded by at least one space. Thus, field 106 would require a space then the number 106. Rule 3: As many fields may be specified as will fit within the FLDLIST field observing the two rules above. For example, to create a data entry menu with fields 1, 7, 21, and 107, FLDLIST should look like the following without the quotation marks which have been included only to assist in showing the spaces: " 1 7 21 107" Once the FLDLIST field has been specified, press CTRL-W or <PgDn> to save the entry. A new blank record will appear. You may continue to add menus or <ESC> to exit to the Main System Menu. Once the Main System Menu reappears, press <ESC>ape to exit to DOS. Then restart WAMPUM in Developer Mode again. When the Main System Menu appears, pick S - Select Utilities and mark the Change Current Menu field as T and <PgDn>. In Developer Mode, three fields will appear below the list of available menus: (1) Number of current menu to use (2) Minimum menu number (3) Maximum menu number For now, press <ENTER> to skip through the current menu field. Then enter a value for the minimum menu number and the maximum which corresponds to the menus you have created and to which you want the users to have access. Remember that if the minimum number is 0, users will be able to access and change every field in the data base! Make certain that BOTH the minimum menu number and the maximum menu number do NOT exceed the value of the last record in the MENUS file. The minimum and maximum menu numbers may be the same number so long as the rule above is not violated. Once you have entered these values <PgDn> if necessary to return to the Main System Menu. Now access the Menu Selection screen again by choosing S - Select Utilities, then mark Change Current Menu true, then <PgDn>. The correct range of menu choices should now be displayed. Now set the value for the current menu to use and <PgDn> to return to the Main System Menu. Now you may SAVE this new configuration by selecting the option G - Configuration Update then pressing <ENTER>. You now are ready to test the application. <ESC>ape to DOS and restart WAMPUM in user mode. Select the A - Add Records option and make certain that the correct menu displays. Press <ESC>ape. Now choose S - Select Utilities and mark Change Current Menu true and <PgDn>. The correct range of menus should - 65 - appear, and you should only be able to enter a number in the range specified. If not, restart WAMPUM in Developer Mode and change the ranges following the steps outlined above. 3.1.14 Building an Audit Trail File (AUDIT.DBF) For a variety of reasons, it may be desirable to create an audit trail of all data added or changed in a data base. This can be done as a means of verifying the accuracy of data posted to the data base. Or it can be done in multi-user environments to provide update integrity to the master data base while many users share access to a copy of the data base from the previous day. In the latter instance, the audit trail serves as a transaction log of new entries to the master data base. These transaction logs can be built using numerous workstatios. Then at the end of the day all of the new transactions can be posted to the master data base using WAMPUM's Copy Utilities. To invoke the AUDIT TRAIL/TRANSACTION LOGGING feature of WAMPUM, you must be using version 2.9 or later of the software. You must assure that some field in your data base has unique values and is indexed before implementing transaction logging. This index must be set as the PRIMARY INDEX before executing a configuration update. Then select the G - Config Update option and change the Enable Audit Trail? prompt to True. Thereafter, WAMPUM will automatically create an AUDIT.DBF file in which it will post any changes to the current data base using the index which was the current index at the time of configuration update as the key field in the event later transaction log posting is desired. It is the developer's responsibility to assure that the AUDIT.DBF file is periodically purged since it will continue to grow indefinitely until the Enable Audit Trail prompt is turned back off by setting it false. Purging consists of deleting AUDIT.DBF and AUDIT.DBT from the current application directory with the following commands: CD \{current application directory} DEL AUDIT.* Once these files are deleted, WAMPUM will recreate them the next time WAMPUM is run in this directory. See the section of the User's Guide which addresses the COPY UTILITIES for infor- mation on posting transactions to the master data base from an audit trail file. 3.1.15 Preformatted Output (WAMPUM.DBF) 3.1.15.1 Overview WAMPUM PreFormatted Output is the feature for which many dBASE users have clamored for years. It is nothing more than a tool by which a developer can "hard-code" ALL required components - 66 - of a report, label, or form letter process in advance. Stated differently, it frees the end-user from having to specify which records should be printed and in what order every time a report is run. How is this magic performed? Very simply. For each new application you develop, WAMPUM will create a separate data base file, WAMPUM.DBF, which stores up to 80 preformatted reports, labels, and form letters. The end user then can call up a list of these preformatted output choices and mark the ones desired as True. These then are produced automatically with no further user intervention. 3.1.15.2 Building the WAMPUM File The first step in developing WAMPUM Preformatted Output is to create the WAMPUM.DBF file to store the information. This is done by selecting W - WAMPUM PreFormatted Output from the Main System Menu. When WAMPUM asks whether to create the WAMPUM file, respond with either T or Y to create the empty data base. 3.1.15.3 Adding/Editing the WAMPUM File Building preformatted output is much like adding and editing data in any other .DBF file. First, pick the F - File Select option from the Main System Menu, and enter WAMPUM as the name of the data base to use. When the Main System Menu returns, the bottom of the screen should show the file in use with the message: FILE: WAMPUM. To create a new entry in the file, select the A - ADD record option. To change an existing entry, select E - EDIT record. When the data entry screen appears, you will be prompted for the following items of information concerning the report, label, or form letter you wish to preformat: DATAFILE - Enter the name of the primary data file which will be used in producing the output. Do NOT include the .DBF file extension. SORTINDX - If you want the output sorted in a particular order, then you may specify the sort index by entering the name of index file. Do NOT enter the .NTX file extension. If this field is left blank, the output will be produced in the actual order of the records in the primary data base. RPTLBLFRM - Enter either R, L, or F to tell WAMPUM whether the output will be a report (.FRM file), label (.LBL file), or form letter (.DBF file). OUTFILE - Enter the name of the actual report form, label format, or form letter file. Do NOT include the file extension. - 67 - FONT - Enter a number between 0 and 9 to identify which FONT will be used in generating the output. See the section on Printer Configuration for more info. CRITERIA - Enter the selection criteria just as they would be entered in the Select Utilities option previously discussed. Note that there is one enhancement. If there is a particular range of dates you want to prompt for at execution time, then you can specify the field to which the date range will apply by surrounding that field with //'s. For example, suppose you were generating a report which would show new job applications received for a certain period of time. If the field name storing the application date was APPLICDT, then the following syntax in the criteria would allow the user to enter a date range at run time for the application date: //APPLICDT//. DESCRIP - Enter a brief description for the output you just designed. This is what will appear on the menu when the user selects WAMPUM Preformatted Output. RELFILE1 - Enter the file name of the file to be related to the primary data base when the output is run. See the section on Z - Zoom/Relate File for more info. RELINDX1 - Enter the file name of the index to be used in relating the secondary file to a field in the primary file. See Z - Zoom/Relate File for info. Once all of the above entries have been made, a new record is stored in the WAMPUM.DBF file. When you have added all of the entries desired. Exit from WAMPUM by pressing <ESC> from the Main System Menu. Then restart WAMPUM and select the W option to try out your new output. 3.1.16 Resetting the Developer Password Beginning with version 2.2, WAMPUM provides the capability to reset the developer password from VOODOO to some other password of your choice. This is done using the DOS ENVIRONMENT and the SET command. To reset the password, you should insert a line such as what appears below in the AUTOEXEC.BAT file in the root directory of the hard disk which will be used to boot the system. SET WAMPUM=MOVOODOO - 68 - The value of the WAMPUM environment variable beginning with the THIRD character becomes the new developer password when the system is restarted. In the case outlined above, the password still would be VOODOO since the first and second characters are ignored. Note that this is anything but a secure system. What it will do is keep the casual or novice user from entering WAMPUM in developer mode accidentally. 3.1.17 Network Considerations Multi-user data base access via NETBIOS-compatible networks adds a whole new dimension to WAMPUM applications. Considerations such as security, passwords, audit trails, record and file locking are but a few of the new worries you will face. The best advice for those just getting started is START SMALL. A few users sharing a simple data base is the best way to get a feel for networks. WAMPUM provides a margin of security and reliable record and file locking. Because of the nature of DOS and the computers which run under DOS, WAMPUM is NOT and CANNOT take the place of the mainframe at your local department store. For many network applications, you may not need WAMPUM to impose password security. If you don't need it, DON'T USE IT! If you do need it, include a line in your AUTOEXEC.BAT file for each computer on the network which says: SET USERID=X. Instead of X, you may assign each user a name if you so desire. Then in a separate subdirectory, run WAMPUM and build a new file called USERS with two character fields of 8 characters each. The field names must be USER and PASSWORD. If desired, you may add a third field named SUPERVISOR which must be a logical field. Once you have created the data base, build an index named USER on the USER field. Then add records to the file for each user on the network giving each user a secret password. If you included the SUPERVISOR field, mark it True for those who should have access to WAMPUM in Developer Mode. When you finish adding all records, exit to DOS and copy both USERS.DBF and USER.NTX into a directory which is part of the DOS PATH. Thereafter, whenever any user runs WAMPUM, he or she will be prompted for a USER NAME and PASSWORD which must be in the file you created. If you decide you no longer wish to require USER NAMES and PASSWORDs, simply delete the SET USERID line from the AUTOEXEC.BAT file for those particular network users. Another consideration of which you should be aware is that Clipper, while permitting read access to an entire file while records in that file are locked, nevertheless imposes a file lock whenever an indexed SEEK is underway. This typically is only for a moment; however, if you run reports against voluminous data bases in which only a few records will qualify for the report, you should be aware that the file will be locked up if you are using an active index during the periods spent searching for - 69 - individual qualifying records in the data base. The file will be unlocked momentarily as each record for the report is found. This may or may not be palatible in a high volume data entry environment. In such environments, you may wish to consider running reports against a duplicate of the data base and indexes or you may wish to run reports during periods in which data entry is not critical, i.e. bedtime. 3.1.18 Making a Backup of the User Application Once you have completed building a new application in its own subdirectory, this then can be saved using the BACKUP command for subsequent use by end-users. When the application is completed, simply type the following command substituting the name of the SUBDIRECTORY in which you built the application for the word SUBDIR below. If you are using a drive other than Drive C, you would want to change the C: as well. BACKUP C:\SUBDIR\*.* A: This will make a copy of the application on a formatted floppy in Drive A. The end user then can take this floppy and restore it to the system on which it will be run with the command: RESTORE A: C:\*.* /S The DOS Restore command automatically will construct the new subdirectory on their hard disk and then copy the application without any user knowledge of file copying. 3.1.19 Writing the Documentation Perhaps the most important step in building a new application is to write some documentation explaining what the system does and how to use it. For ease of use, the WAMPUM User's Guide has been paginated in such a way that the end-user section can be extracted and used as the first section of your completed documentation for any new application. Don't distribute new applications without documentation! It gives WAMPUM and yourself a bad name. 3.2 ! - RUNning an External Program Assuming you have sufficient memory, external programs can be run from within WAMPUM using the !- Run External Program option on the Main System Menu. The following programs can be run: executable programs in either .EXE or .COM format and DOS batch files with .BAT file extension. In addition, you can exit to the DOS level temporarily by entering \COMMAND.COM as the file name to run. Note, this only works with DOS 3.0 and above. - 70 - Similarly, directory paths may precede program names with DOS 3.0 or above. Any program within the DOS PATH may be run without specifying the directory path. 3.3 Z - ZOOMing or RELATing a Supplemental File WAMPUM provides the capability to link a secondary file for purposes of report, label, and form letter output. This can be done automatically within the WAMPUM Preformatted Output option, or it can be done manually using the Z - Zoom/Relate File option. There are many instances in which it is helpful to have a secondary file to provide "table lookup" of data which otherwise would have to be retyped in each record of a data base. For example, if each customer has an ACCOUNT NUMBER, it would be silly to build an orders file which required the entry of the customer's name, address, and phone number every time an order was placed. Instead, the orders file could contain the customer number, and a secondary file could be used to "look up" the customer's name, address, and phone number whenever a report, label, or form letter was produced. There are four prerequisites for relating a secondary file with WAMPUM. (1) There must be an IDENTICAL field in both the main data base and the related file; (2) the key field in the related file must be indexed on that key; (3) the index file name must be identical to the name of the key field; and (4) both the related file and its index must either be in the default directory or must be accessible via the DOS PATH. To link a secondary file, pick the Z - Zoom/Relate File option on the Main System menu. Then enter the name of the secondary file and the index. When the Main System Menu reappears, the last line of the screen will show a relation is in effect with the following expression: FILE: ORDERS/R Fields in the related file may then be accessed within report and label forms as well as within form letter files using the following syntax: ALIAS->FIELDNAME where ALIAS is the name of the related file and FIELDNAME is the field name to be output. See the example below for further clarification: CUSTOMER ORDER FILE (ORDERS.DBF) CUSTOMER FILE (ACCOUNTS.DBF) -------------------------------- ---------------------------- ACCTNO ---- RELATED FIELD ---> ACCTNO (INDEXED) ORDERDT CUSTNAME ITEMS ADDRESS PHONE - 71 - As a FIELD CONTENTS entry in the report form, you could then specify ACCOUNTS->CUSTNAME once the ACCOUNTS file was related using the ACCTNO index. This would tell WAMPUM to output the actual customer name rather than the account number found in the orders file. 3.4 G - Global Replacement of Data There are occasions in which it is desirable to replace different pieces of data in a file for a large number of records in one pass rather than calling up each record individually. WARNING: Be aware that the potential for disaster goes up dramatically any time you are replacing data simultaneously for more than one record! If you are new to WAMPUM and particularly to the power of dBASE III's REPLACE command, STAY AWAY FROM THIS OPTION! This feature has been added to WAMPUM against my better judgment because of the pleas of many experienced dBASE users. I fear that the howls from mistakes may far outweigh the benefits. If you do not need the temptation of this option, delete item 18 from the Menu # list when you configure new WAMPUM applications! G - Global Replace is a function closely akin to global search and replace on many word processing systems. It involves (1) selecting a group of records to be processed and then (2) revising one or more fields of data in the records which meet the selection criteria. If you already have entered Selection Criteria, then executing G - Global Replace always works with the group of records meeting those search criteria. If you have not already entered Selection Criteria, then selecting G - Global Replace always triggers WAMPUM's Select Assist first. You must enter selection criteria before Global Replace will work. You are well advised to run a list using the Select Criteria you have in mind for Global Replace to make sure the correct records have been selected. Once Global Replace has been executed, it's too late to get them back! See the Select Utilities section of the User's Guide for more details. Once record selection criteria are in effect, G - Global Replace will display the Global Replace Screen which permits you to specify up to 10 different fields which can be updated in one pass through the data base. For each field, you specify two pieces of information: (1) the field name and (2) the dBASE string expression to be executed against that piece of data. In its simplest form, you may wish to replace all DUE DATES with a new value 30 days later than the existing date. Assuming you already have selected the range of records to be changed, the correct procedure would be to use the <Up> or <Down> arrow to first find the DUEDT field. Once displayed, press <ENTER>. When prompted for the string expression, enter the following: - 72 - DUEDT+30. Then press <ENTER>. If there is another field to be replaced, you would leave the LINK in the AND display and press <ENTER>. A second line would permit you to repeat the above process for another piece of information. When finished, simply press <PgDn> while the cursor is in the LINK field and the global search and replace will proceed. If you have made a mistake, press <ESC> to exit without executing the global replace! If a group of last names had been entered in upper and lower case and you wanted to convert them to ALL UPPER CASE, you would first specify the group of records to be processed using SELECT ASSIST. Then, when the GLOBAL REPLACE SCREEN appears, find the LASTNAME field, press <ENTER>, type UPPER(LASTNAME) for the field expression, press <ENTER>, and <PgDn> to proceed. If a last name of a customer changed from JONES to JOHNSON (and you're sure using Select Assist that you have narrowed down the group of records to the correct JONES only), then, when the GLOBAL REPLACE SCREEN appears, find the LASTNAME field, press <ENTER>, type "JOHNSON" for the field expression, press <ENTER>, and <PgDn> to proceed. MORAL: Always RUN A LIST against your existing SELECTION CRTIERIA to make certain that only the desired records will be REPLACED before executing G - Global Replace. If you're new to WAMPUM and data base management, make a full backup of your data base application before using this option! Don't say you haven't been warned! 3.5 C - Copy Utilities for Importing & Exporting Data WAMPUM's C - Copy Utilities option provides a rich variety of file importing and exporting tools permitting standard dBASE data bases to be transferred into or out of virtually all of the common file formats. In addition, a data base structure file can be created which permits simple revision of a data base structure where additional fields become desirable after an application has been built. With the exception of the dBASE III structure and audit trail options, you can narrow down which records will be copied by first specifying selection criteria using the S - Select Utilities option. You will be prompted whether to override the selection. When the C - Copy Utilities option is selected, you initially are prompted for three pieces of information: (1) whether you will be COPYing data TO or FROM another file from the file currently in use; (2) the file type of the other file; and (3) the file name of the other file. Copying TO Another File requires that the first prompt be answered with a T. Then a file type is specified. And then the file name of the receiving file is specified. - 73 - If you specify a dBASE III type data base file as the receiving file, then one will be created if the file name specified does not already exist. If it exists, you will be asked whether to Abort, Overwrite, or Append to the existing external file. If you specify COPY TO a dBASE III Structure, WAMPUM will copy the structure of the current data base into a new .DBF file with four fields: Field_Name, Field_Type, Field_Len, and Field_Dec. Each record entry in the new file will match a field in the structure of the current data base. This file then can be added to, edited, records can be deleted, etc. Once revised, this file then can be used as the new file structure template for transferring the current data base into a new file structure. This is covered in detail below. If you COPY TO a Standard Data Format file, WAMPUM will create a new flat file consisting of all the selected data in the current data base in ASCII format. Each record will occupy one line in the new file with a carriage return/line feed at the end of the line. COPYing TO a Delimited Format file permits the user to identify what character should be used to surround each character field in the new data base. For example, BASIC expects character fields in a sequential file to be delimited with QUOTES. COPYing TO an Audit Trail file is never permissible. You may edit the AUDIT file just as you would edit any other file. COPYing TO an Empty dBASE III file makes a duplicate empty data base file with the same file structure as the current file in use. Copying From Another File means that you will be IMPORTING data from another file INTO the data base file currently in use. The only exception is the dBASE III Structure option covered below. To COPY FROM another file, enter F at the To/From prompt. If you COPY FROM another dBASE III data base, then the information in ALL records in that data base will be appended to the data already in the current data base. Only field data whose field names and type match exactly those of the current data base will be copied. Existing records in the current data base will not be deleted. If you COPY FROM a Standard Data Format file, its records are appended to the information, if any, which already exists in the current data base. Note that the current dBASE III file structure should be created first to match the format of the SDF file. If you don't understand this, obtain a good dBASE III Primer before attempting to use this option or the next one. - 74 - If you COPY FROM a Delimited file, its records are appended to the information, if any, which already exists in the current data base. Note that the current dBASE III file structure should be created first to match the format of the delimited file. COPYING FROM a dBASE III Structure is WAMPUM's way of allowing you to modify the structure of the current data base and move the file contents to a new dBASE III file. To modify a file's structure, follow the steps outlined above to create and revise a new dBASE III structure file. Once completed, place the original dBASE III data base file back in use with F - File Select. Then pick the COPY FROM option and specify option 2, a dBASE III Structure. Enter the name of the structure file as the external file. You then will be prompted to enter a name for a new dBASE III data base file to be built using the new structure and the data from the data base file currently in use. Enter a name of your choice and press <ENTER>. Once completed, place the new file in use and check the data to assure that it copied what you intended before deleting the old data base! Once you are certain that it looks the way it should, you should reindex the file following the instructions in the I - Index Select/Create section of this User's Guide. You then can delete the original data base preferably after making a backup copy to a floppy. COPYING FROM an Audit Trail file is WAMPUM's way of allowing posting from a transaction file. To use this option requires version 2.9 or later of WAMPUM. In addition, the developer must have set the AUDIT TRAIL flag True for this application when the G - Config Update option was run. And, the audit flag must be set to False before posting to the master data base begins. Assuming the above conditions have been met, a file will exist in the default directory named AUDIT.DBF. This should be entered as the external file name or simply enter the drive designator indicating the drive location of the AUDIT files, e.g. C: or A: with a floppy. For the transaction posting to work, the current file and lead index must match the file and lead index designated when the audit trail file was created. Otherwise, an error message will be given indicating what the required file and index must be. If no error condition is present, then WAMPUM will post all information in the audit file to the current data base and will notify the user when this has been completed. Remember that the values in the lead index must be unique or the AUDIT file will be posted to the first matching key found in the index. Note also that this function is accessible only to users with the developer password. 3.6 Deleting & Undeleting Groups of Records WAMPUM provides a means of marking a group of records as DELETED as well as a means of restoring a group of records which already have been marked for deletion. To use this function, you must start WAMPUM with the Developer Password! You also must have specified Record Selection Criteria, and there must be a primary index which evaluates to a character expression. If any - 75 - of these three prerequisites is missing, WAMPUM ignores the attempt to delete or undelete a group of records just as if the function did not exist. Once the above prerequisites have been satisfied, you should first run a sample listing using the List File Contents option in the S - Select Utilities. This will assure that you are working with the group of records desired. Next, pick the function desired: either M - Mark Records *DEL* or U - UN*DEL* Records. When WAMPUM prompts for the entry to find, type an asterisk (*) and press <ENTER>. If the prerequisites in the first paragraph have been met, WAMPUM will ask if you really want to DELETE or RESTORE the selected group of records. Type Y if you want to proceed, or press <ESC> to abort. This function provides a quick way to mark a large group of records deleted once the same group of records has been archived to a different file. When the X - Rebuild/FileFix option is then run, the group of records is deleted permanently and cannot be restored with the U - UN*DEL* Records function. Note that this function requires an active Record Selection Criteria expression to avoid the possibility of marking every record in a file as deleted. If you really want to delete all records in a file, use the following Record Selection Criteria: RECNO() >= 1 This expression specifies ALL RECORDS in the file for WAMPUM. 3.7 Reserved Variables, dBASE & Clipper Functions _____ _______ 3.7.1 Overview In addition to a number of reserved functions provided in the standard implementation of the dBASE III programming language, WAMPUM adds all Clipper enhancements plus some new functions of its own. This section is designed to bring you up to speed on these new functions and some of the major dBASE III commands and functions. It is by no means an exhaustive treatment of all dBASE III functions. Consult any of the dBASE III reference books in your local bookstore for more information on the dBASE III commands and functions. 3.7.2 CHARACTER/STRING functions Character string manipulation becomes critical in producing meaningful reports and form letters. WAMPUM provides a rich assortment of functions to assist the developer. As is true of all functions, each contains a keyword followed by parentheses, one or more arguments separated by commas, and closing parentheses. - 76 - AT(exp1,exp2) allows a search of the second string expression for the first occurrence of the first expression. A numeric value is returned for the character position of the first match. For example, AT("son","Thompson") would return 6. If no match is found, a 0 is returned. CHR(n) returns an ASCII character represented by ASCII code n. For example, CHR(27) is the escape code. SPACE(n) allows the generation of n spaces where n is a numeric value. For example SPACE(5) produces 5 spaces. STR(exp1,n,dec) converts a numeric expression (exp1)into a string expression n characters long with dec decimals. For example, STR(153.123,5,1) would yield "153.1". SUBSTR(exp1,n,len) permits extraction of a portion of a string from a larger string. n is a numeric specifying the starting position in the exp1 string. len is a numeric specifying the number of characters to extract from the starting position. For example, SUBSTR("Thompson",3,2) would return "om" which is 2 characters beginning at character position 3. TRIM(exp1) tells WAMPUM to trim off trailing spaces from a character string. For example, if a 30 character NAME field contained "John Jones " then TRIM(NAME) would yield "John Jones" with no trailing spaces. UPPER(exp1) converts a string expression to all UPPERCASE. The converse is LOWER(exp1) which does the opposite. VAL(exp1) returns a numeric value for the exp1 string. For example, VAL("02345") would return the integer 2345. 3.7.3 DATE functions WAMPUM supports the dBASE III function for today's date which is DATE() as well as the reserved word TODAY which also is today's date in date format. The standard dBASE III means of converting a date to a character string is supported. DTOC(DATE()) would convert today's date to a character string in the format 06/12/86. The converse also works to convert a string to a date: CTOD("06/12/86") would convert the string to a date variable. Several DAY functions are available including CDOW() which outputs the actual day of the week such as Monday; DAY() which produces a numeric representing the day of the month such as 31; DOW() which produces a numeric representing the day of the week such as 5. Note that an empty date field always produces DOW equal to 0. This is a good way of testing for blank dates. - 77 - Several MONTH functions also are available. MONTH() outputs a numeric representing the month of the year such as 2. CMONTH() generates the actual name of the month such as February. dBASE III also supports YEAR() which outputs a 4-digit numeric value representing the year such as 1987. Clipper provides a date-to-string conversion function with the DTOS() command. The syntax is DTOS(FILINGDT). Assuming a filing date of 10/10/85, DTOS(FILINGDT) would output the string "19851010". This function is particularly helpful in building indexes where a date field is converted to a string, but the developer wishes to preserve the proper ordering of dates. In producing reports and labels, you can reformat a date field into a standard date character string using the WAMPUM function FULLDATE(). The syntax is FULLDATE(FILINGDT) assuming FILINGDT was a date field in your data base. If the filing date were 10/20/85, FULLDATE(FILINGDT) would output October 20, 1985. In some applications, it may be desirable to roll a date over to Monday if it hits on a weekend. WAMPUM's WEEKDAY() function does this. Assuming a filing date of 06/14/86 hits on a Saturday, the expression WEEKDAY(FILINGDT) would return a date expression with a value of 06/16/86 which is the following Monday. Note that this function could be combined with a previous one to produce a standard text date:FULLDATE(WEEKDAY(FILINGDT)). 3.7.4 DUPKEY("FIELDNAME") prevents duplicate keys When building the EDIT.DBF edit checks, many users expressed a desire to be able to test whether the key field of the record being added to a data base already existed and, if so, to return an error. This is critical if you will be using the AUDIT TRAIL function. The DUPKEY function of WAMPUM provides this capability. In order to use it, the following conditions must be met. First, the key field to be checked must be indexed. Second, that index must be the primary (first) index in use when the file is ADDed to or EDITed. Finally, the name of the key field must be specified in parentheses and quotation marks as an edit check in the EDIT.DBF file. The syntax is shown in the following example using PARTNO as the name of the indexed key field which is to be checked: DUPKEY("PARTNO") 3.7.5 EMPTY(fieldname) tests for empty fields EMPTY(FieldName) returns a logical True if a character, memo, or date field is empty, or if a numeric field is 0, or if a logical field is False. Otherwise, a logical False is returned. - 78 - 3.7.6 LASTTIME field in data bases If LASTTIME is included as a Character-type field in any data base, WAMPUM will automatically post the current time to this field whenever a record is ADDed or EDITed in that data base. This provides a convenient method of determining when records were last updated with no user control over the field contents. 3.7.7 LASTUPDT field in data bases If LASTUPDT is included as a Date-type field in any data base, WAMPUM will automatically post the current date to this field whenever a record is ADDed or EDITed in that data base. This provides a convenient method of determining when records were last updated with no user control over the field contents. 3.7.8 LASTUSER field in data bases If LASTUSER is included as a Character-type field in any data base, WAMPUM will automatically post the current USERID to this field whenever a record is ADDed or EDITed in that data base if the SET USERID=X line has been added to the AUTOEXEC.BAT file for each network user. This provides a convenient method of determining who screwed up what with no user control over the field contents. Please note that before using the SET USERID=X command, you must first create a USERS data base and index with the names and passwords of those authorized access to WAMPUM. 3.7.9 MEMOTRAN(fieldname) outputs MEMO fields MEMOTRAN(FieldName) is a Clipper function designed to assure that MEMO fields are output correctly in reports. See the discussion in the Reports section of this User's Guide. 3.8 PATH considerations Whenever WAMPUM is started, part of its initialization process includes reading the DOS PATH which then becomes WAMPUM's PATH as well. For this reason, developers need to be careful NOT to build WAMPUM applications in a directory which is part of the DOS PATH since all of the files in this directory then would be accessed by other WAMPUM applications. What should be stored in a directory supported by the DOS PATH command are the following files: WAMPUM.EXE, REPORT.EXE, LABEL.EXE, and the printer config files such as HPLASERA.MEM, HPLASERB.MEM, and EPSON.MEM. This will make all of these files accessible to users in any WAMPUM subdirectory. The only exception to these guidelines might be in situations in which a related file and its index need to be shared with several different applications. In this case, just - 79 - the related file and index should be placed in a directory supported by the DOS PATH command, NOT the configuration files for the WAMPUM application itself. If you don't understand this exception, don't use it. 3.9 Enabling USERID's and Passwords WAMPUM now may be configured to require those accessing files through WAMPUM to log in with a USERID and PASSWORD. Typically this would be used for network applications if the network itself does not provide adequate protection. The USERID- PASSWORD system also may be invoked in single-user applications. Step 1 to force use of the USERID-PASSWORD system is to create a data base which will store the user names and passwords of those authorized to utilize WAMPUM. Create a new subdirectory on your hard disk and run WAMPUM in Developer Mode. Then Build A New File and name it USERS. Two fields must be created in this file structure. Two additional fields are optional. The two mandatory fields are USER and PASSWORD. Both fields must be Character-type fields with a field length of 8. The optional fields are SUPERVISOR, which must be a Logical field of length 1, and CONFIG, which must be a character field of length 8. Once you have built the new data base, use File Select to place the USERS file in use. Then use Index Select/Create to build an index on the USER field. You then are ready to ADD records to the data base for each anticipated user. For each user, you must include a user name and password. THESE ENTRIES BOTH MUST BE IN ALL UPPER CASE LETTERS! Once you have added all the entries desired, exit to the DOS level and copy USERS.DBF and USER.NTX into a directory which is part of the DOS path. This will enable WAMPUM to find the files whenever an attempt is made to run WAMPUM. Assuming your \DOS subdirectory is part of the path, a simple command to copy the files would be as follows: COPY USER*.* \DOS Whenever you wish to add new users, move to the directory in which you established the original copy of the file (NOT the directory which is part of the DOS PATH!). Add whatever new entries are desired, and then recopy the file to the same directory sharing the DOS PATH which was used previously. If you accidentally get tangled up to the point that you cannot get into WAMPUM, you can turn OFF the password feature by disabling the USERID variable in the environment. To do this, exit to DOS and type the following command at the DOS prompt: SET USERID= If the SUPERVISOR field is used and is marked True for a given user, then WAMPUM automatically will be started in Developer mode for that user. This means that the expanded menu of 21 options will be displayed for this user. - 80 - If the CONFIG field is used, then the developer may specify a configuration file for use by each user. This configuration file takes the place of WAMPUM.MEM which will be used unless the CONFIG field is used and has an entry. The process for generating these individual configurations is quite simple. Create a new WAMPUM configuration as you normally would using the * - Config Update option. Then exit to DOS and copy the WAMPUM.MEM file which was created to a new filename making certain that the file extension remains .MEM. Then edit the USERS data base and add an appropriate CONFIG file name for the users desired. For example, let's assume there is a USER named Jones. We want that user's CONFIG file to be named JONES.MEM. Run WAMPUM in Developer Mode and configure the application in the normal manner. Now exit to DOS and type COPY WAMPUM.MEM JONES.MEM. Revise Jones' entry in the USERS data base to reflect a CONFIG field value of JONES. That's all there is to it. 3.10 WAMPUM & DOS System Errors WAMPUM System Errors are error conditions caused by one of three conditions: (1) a DOS-error is detected, (2) a Clipper error is detected, or (3) the abort program key (ALT-C) is pressed by the user. In any of these three situations, a system error message appears on the top line of the screen followed by a prompt. Simply follow the directions to proceed. 3.11 Credits The following are trademarks or registered trademarks of the respective companies: Clipper Nantucket Corp. dBASE, dBASE III, and dBASE III Plus Ashton-Tate LOTUS, 1-2-3, and Symphony LOTUS Development Co IBM, IBM PC, and IBM PC-AT IBM Corporation HP LaserJet, Plus, and LaserJet II Hewlett Packard - 81 -